IBM Cloud Docs
Format

Format

APIs MUST support JSON by default for sending and receiving data in request and response bodies. Other formats SHOULD NOT be supported except to meet a compelling industry-specific need.

Object encapsulation

All JSON data MUST be structured in an object at the top level; arrays MUST NOT be returned as the top-level structure in a response body.[1]

Request body constraints

Services MUST have a documented and enforced maximum payload size for request bodies. Requests with bodies larger than the limit MUST be rejected with a 413 Payload Too Large status code and appropriate error response model.

If the request body size can be determined from the request headers, the request MUST be rejected prior to any processing of the payload[2]. For chunked transfer or other cases where the request body size cannot be predetermined, the request SHOULD be rejected as soon as it has been determined to exceed the limit.

Content-Type behavior

If a request Accept header is either not provided or matches[3] application/json, the response MUST be JSON and its Content-Type header MUST be application/json.

JSON processing

Case insensitivity

Field names in JSON objects in a request payload SHOULD NOT be case-normalized to support case insensitivity; a field that does not match the case of a defined field but otherwise matches its name SHOULD be treated as any other extraneous input[4].

However, field name case normalization MAY be supported for backward compatibility with existing clients.

Ambiguous JSON data

Duplicate field names MUST NOT exist in any one JSON object[5] contained in a JSON response. If duplicate field names exist in an object within a request payload, the request MUST be rejected [6] with a 400 status and appropriate error response model.

Be aware that the JSON specification itself does not strictly prohibit duplicate field names in a single object and many unmarshalling libraries may silently choose from among duplicated fields.

If a service supports field name case insensitivity, field names MUST be normalized prior to validating uniqueness.

Cross-origin support

If a service has a need to support cross-origin requests, CORS headers SHOULD be supported to enable this. The JSONP format SHOULD NOT be supported.

  1. This design allows for top-level metadata to be added later and prevents a cross-site scripting vulnerability. ↩︎

  2. Specifically, a service SHOULD NOT attempt to parse the JSON in a payload prior to checking and enforcing the size limit. ↩︎

  3. It's very important to note that API implementations should not parse Accept headers with a simple string search for application/json, as wildcards are often used. It's also important for matching to be case-insensitve, as MIME types are lowercase by convention only. ↩︎

  4. Case normalization is often an error-prone process, however simple it may seem. One problem is that different standard libraries may not agree on the lowercase-equivalent value for a particular string. For example, "İstanbul".ToLowerCase() in JavaScript yields i̇stanbul (note the two dots over the first character), but strings.ToLower("İstanbul") in Go is more aware of locale-specific rules and yields istanbul. If the code that validates and the code that actually uses a particular field disagree on the normalization of its name, it could lead to a bug that could be exploited to validate one value and use another. ↩︎

  5. Using the same field name in different objects within a single JSON payload is perfectly acceptable. ↩︎

  6. Silent support for ambiguously duplicated fields in JSON documents increases the risk that a malicious client could craft a JSON document that bypasses critical authorization or validation checks. ↩︎