ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-316] Response: primary type ​

reviewing phase 1

Explain custom json type good parts.

Guidance ​

  • MUST use JSON as the primary type of API response unless the API is designed for binary data transmission. Custom JSON media types are also acceptable.
  • MUST use appropriate Content-Type headers to indicate the response format.
  • SHOULD use standard media types when possible, as defined in the IANA Media Types registry.
  • MAY use custom media types for specialized JSON responses, following the format application/vnd.{organization}.{type}+json.

Examples ​

Standard JSON Response ​

DO:

http
GET /term-of-service HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "term-of-service": "In our service ..."
}

DON'T:

http
GET /term-of-service HTTP/1.1

HTTP/1.1 200 OK
Content-Type: text/plain

In our service ...

Custom JSON Media Types ​

Custom JSON media types can be used to specify the nature of the JSON response more precisely.

Example:

http
GET /user/profile HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.myapp.user-profile+json

{
  "id": 12345,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Binary Data Transmission ​

If the API is designed for binary data transmission, such as downloading an image or file, the response should use the appropriate binary Content-Type.

Example:

http
GET /download/image HTTP/1.1

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="image.png"

(binary data)

Best Practices ​

  1. Consistency: Maintain consistent use of media types across your API.
  2. Versioning: When using custom media types, consider incorporating version information (e.g., application/vnd.myapp.v1+json).
  3. Documentation: Clearly document all supported media types in your API documentation.
  4. Content Negotiation: Implement proper content negotiation to handle different Accept headers from clients.

References ​