sefe / sefe/dorc

Standardize API error responses to a single error field

Open
#752 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement tech-debt
Dominant language
C#
Stars
5
Forks
3
Avg merge
1d 22h
Merged PRs (30d)
14

Description

Background

Follow-up from PR #751 review (thread: https://github.com/sefe/dorc/pull/751#discussion_r3473989924).

Different API endpoints currently return error information in different shapes — a bare JSON string (BadRequest("…")), a DTO with a Message property (e.g. CopyEnvBuildResponseDto), serialized exception objects (StatusCode(500, exception)), and ASP.NET ProblemDetails (title/detail). To cope, the client ApiCaller.ExtractErrorMessage (src/Dorc.Core/ApiCaller.cs) has to probe several candidate fields, which is fragile and easy to get wrong.

Goal

Standardize on a single error contract returned by every API endpoint, so clients read one field.

Proposed scope

  1. Define one error-response shape (e.g. { "error": "…" }, or ASP.NET ProblemDetails with a single agreed field) and document it.
  2. Update controllers to return that shape consistently for 4xx/5xx, and stop returning raw exception objects / stack traces to clients (use a correlation id; log details server-side). This overlaps with a separate security concern about verbose error/stack-trace disclosure across the API (DefaultExceptionHandler and several controllers returning StatusCode(500, e) / error + " - " + ex).
  3. Simplify ApiCaller.ExtractErrorMessage to read the single field once the server side is consistent.
  4. Add/adjust tests.

Notes

  • Cross-cutting change touching most controllers — intentionally kept out of PR #751 to keep that PR scoped.
  • Once done, the multi-field probing added in #751 can be removed.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/Dorc.Core/ApiCaller.cs, DefaultExceptionHandler, and the controllers returning StatusCode(500, e) or mixed error shapes; review the response types such as CopyEnvBuildResponseDto and the discussion from PR #751. Define and document the single agreed error field, update the affected 4xx/5xx responses, remove multi-field probing, and add or adjust tests confirming consistent responses without raw exception details.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, backend-api-design, security
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.