1. Introduction
=============

JsonDispatch is a **lightweight API response specification** built on top of JSON. It defines a predictable, flexible response envelope for REST APIs so clients always know where to look for the status, data, and helpful metadata.

Think of it as the **contract** between your backend and your clients (mobile, web, services). Instead of every project reinventing its own shape, JsonDispatch gives you:

- **Consistency** — the same envelope across all endpoints.
- **Traceability** — every response carries a server-generated ``X-Request-Id``.
- **Clarity** — clean separation between ``success``, ``fail``, and ``error``.
- **Flexibility** — optional ``_references``, ``_properties``, and ``_links`` for richer responses.

1.2 Why another spec?
--------------------

If you've worked with APIs before, you've probably seen:

- ``{ "ok": true }`` here,
- ``{ "status": "success", "payload": … }`` there,
- and somewhere else … a raw stack trace in JSON.

This chaos makes it hard to build **generic clients**, reason about failures, and correlate logs across services. JsonDispatch standardizes the response shape while staying practical and easy to adopt in real systems.

1.3 Core Principles
------------------

JsonDispatch is built around a few simple rules:

**Never remove, only add**

Responses evolve, but we don't break clients. Deprecate fields instead of deleting them.

**Trace everything (server-generated IDs)**

The server **must** generate and return a unique ``X-Request-Id`` on every response (clients don't send it). This makes correlation and debugging straightforward.

**Clear status semantics**

- ``success`` → everything worked,
- ``fail`` → the request was invalid (validation, preconditions, etc.),
- ``error`` → the server or a dependency failed.

**Flexible metadata when you need it**

- ``_references`` → turn IDs into human-friendly values,
- ``_properties`` → describe the data shape, pagination, and deprecations,
- ``_links`` → make collections navigable.

**Versioned but predictable**

- Requests send ``X-Api-Version`` (full SemVer) to declare the desired API version.
- The response carries ``X-Api-Version-Selected`` (full SemVer) to confirm the version actually served.
- ``Accept`` uses the JsonDispatch vendor media type (e.g., ``application/vnd.infocyph.jd.v1+json``) on JSON endpoints.