[ADP-317] JSON response

Guidance

• SHOULD use JSON as the top-level response.

  TIP

  To clarify, SHOULD NOT use an array as the top-level response. This approach allows for flexibility in case metadata needs to be injected into the JSON object in the future, such as hypermedia links. Besides, using array as top level response has the security concern, see the reference link.

• SHOULD use the collection name in camel case as the property for collection results in GET methods.

• SHOULD use the action name in camel case as the property for action-based requests with POST methods.

  POST /search HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    search: [],
  }
  
  POST /users/batch HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    batch: [],
  }

• SHOULD use the collection name in camel case if the last path segment is a modifier to the resource collection.

  GET /products/most-popular HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    products: []
  }

Design Thinking

The rule is design for metadata in JSON response. It’s difficult to put metadata in an array.

The tricky part occurs for the collection response to GET requests.

Since we define:

• The collection in the URI should use kebab case.
• The property name should use camel case.

We transform the kebab case of the collection name to camel case when returning it as the plural result.

To be consistent with the rule above, use the action as the property name in action-based request cases.

However, for the modifier case, the subject is the collection, so we should still return the collection.

Example

DO

GET /planets HTTP/1.1

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

{
  planets: []
}

---

GET /dwarf-planets HTTP/1.1

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

{
  dwarfPlanets: []
}

DON’T

GET /universes HTTP/1.1

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

[{ id: 0 }]

Reference

Design Reference

• MUST NOT use array as top level response