HTTP responses

RespKit provides helpers for successful responses, errors, created resources, and responses with no body. The default response format is an envelope. You can choose RFC 9457 Problem Details for errors when creating an engine.

Response helpersCopy Anchor Link

Each helper returns an error. Handle it according to the framework in use. It indicates an unsupported context or a response-writing failure. Do not try to write a second response if the first one may already have been sent.

Successful responsesCopy Anchor Link

The default envelope keeps application data under data and uses snake_case for RespKit-owned keys:

{
  "success": true,
  "data": {
    "user_id": 123,
    "name": "Ada"
  }
}

resp.Created returns the same envelope with status 201. Use resp.Location to set the resource's Location header:

return resp.Created(ctx, user, resp.Location("/users/123"))

resp.NoContent returns status 204 without a response body. Requests using the HEAD method also receive no body.

Errors with the default envelopeCopy Anchor Link

An unknown resource maps to a stable public code and a localized message. This example uses the English catalog:

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Validation errors can include field-level details. Only include values that are safe to return to the client:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submitted data is invalid.",
    "details": [
      {
        "field": "email",
        "code": "FIELD_REQUIRED",
        "message": "The email field is required."
      },
      {
        "field": "name",
        "code": "MIN_LENGTH",
        "message": "The name field must be at least 3 characters."
      }
    ]
  }
}

Errors with RFC 9457 Problem DetailsCopy Anchor Link

Select resp.ProblemDetails when creating an engine:

api, err := resp.New(resp.WithErrorFormat(resp.ProblemDetails))
if err != nil {
	return err
}

return api.Fail(ctx, resp.ErrNotFound)

The same 404 error is then represented as Problem Details:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "RESOURCE_NOT_FOUND"
}

The response uses application/problem+json. Problem Details changes error responses only. Successful responses continue to use the RespKit envelope.

Headers and HTTP behaviorCopy Anchor Link

• JSON responses use the JSON UTF-8 content type. Problem Details errors use application/problem+json.
• Content-Language identifies the language used in the response. Vary: Accept-Language helps caches that vary by request language.
• A safe X-Request-ID header can be copied into response metadata.
• resp.Created can set the Location header with resp.Location(url).
• A 204 response and a response to a HEAD request have no body.
• A 401 response includes WWW-Authenticate: Bearer by default. Configure a challenge that matches the authentication scheme used by the application.

The envelope naming option affects RespKit-owned keys only. Application data is returned without changing its JSON keys.