Response Structure — Proposed Guide

Response Structure: Response envelopes would separate the resource representation from pagination and diagnostic metadata. A successful HTTP response does…

Overview

Response envelopes would separate the resource representation from pagination and diagnostic metadata. A successful HTTP response does not by itself mean that an expense is approved, reimbursed or reconciled.

Key concepts

Read resource status from the data object and request correlation from metadata. Collection envelopes contain an array; a retrieve envelope contains one object.

Implementation considerations

Treat missing required fields as a contract problem rather than silently constructing an approved record. Future schema validation should preserve unknown optional fields when forwarding data.

Proposed API behavior

GET /v1/expenses/exp_example_123 is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Static example requests

# Proposed request text only; this reserved host is not a live API.
curl -X GET 'https://api.remizen.example/v1/expenses/exp_example_123?status=draft' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Fictional response example

{
  "data": [
    {
      "expense_id": "exp_example_123",
      "version": 1,
      "id": "exp_example_123",
      "organization_id": "org_example_123",
      "merchant": "Example Office Supply",
      "amount_minor": 12550,
      "currency": "USD",
      "status": "draft"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Treat missing required fields as a contract problem rather than silently constructing an approved record. Future schema validation should preserve unknown optional fields when forwarding data.

{
  "error": {
    "code": "validation_error",
    "message": "The proposed response structure operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Related documentation