JSON API Standards
0 likes97 views
This document discusses the JSON API standard for formatting JSON responses. It provides conventions for API documentation, including required members like "data" and "errors" at the top level of JSON responses. It also outlines standards for creating, updating, and deleting resources through APIs, such as returning a 201 status code when creating a resource and a 204 code when deleting a resource successfully. The document aims to help developers avoid debates about JSON formatting through a standardized approach defined by the JSON API specification.
JSON API Standards
- 2. HELLO! Lucas Bicca E-mail: [email protected] Twitter: lucaslbs15
- 4. “If you'he ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool. {json:api}
- 5. WHAT IS BIKESHEDDING PATTERN? {json:api}
- 6. WHAT IS BIKESHEDDING PATTERN? Some people have commented that the amount of noise generated by a change is inversely proportional to the complexity of the change. {json:api}
- 7. JSON API CONVENTIONS Focus on what matters: your application!!! {json:api}
- 8. MUST MUST NOT REQUIRED SHALL SHALL NOT JSON API CONVENTIONS SHOULD SHOULD NOT RECOMMENDED MAY OPTIONAL {json:api}
- 9. Top Level A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document's "top level". {json:api} JSON API CONVENTIONS
- 11. JSON API CONVENTIONS MUST A document MUST contain at least one of the following top-level members: data, errors and meta. MUST NOT The members data and errors MUST NOT coexist in the same document. MAY A document MAY contain any of these top-level members: jsonapi, links and included. {json:api}
- 16. SHOULD The page query parameter is reserved for pagination. Servers and clients SHOULD use this key for pagination operations. RECOMMENDED To enable an easy mapping of member names to URLs, it is RECOMMENDED that member names use only non-reserved, URL safe characters in RFC 3986. MUST NOT The server MUST NOT interpret missing attributes as null values. JSON API CONVENTIONS {json:api}
- 17. CREATING RESOURCES The request MUST include a single resource object as primary data. The resource object MUST contain at least a type member. {json:api}
- 19. CREATING RESOURCES - RESPONSE The server MUST return a 201 Created status code if request did not include id. The response SHOULD include a Location header identifying the location of the newly created resource.
- 21. UPDATING RESOURCES The PATCH request MUST include a single resource object as primary data. The resource object MUST contain type and id members. It MUST NOT interpret them as null or empty values. {json:api}
- 23. UPDATING RESOURCES - RESPONSE ▸ 202 Accepted: if an update request has been accepted for processing, but the processing has not been completed by time the server responds; ▸ 200 OK: if an update is successful, the client's current attributes remain up to date. The server MUST NOT include a representation of the updated resource(s).
- 24. DELETING RESOURCES {json:api} The server MUST delete the specified members from the relationship or return a 403 Forbidden response.
- 26. DELETING RESOURCES - RESPONSE ▸ 404 Not Found: a server SHOULD return a 404 Not Found status code if a deletion request fails due to the resource not existing; ▸ 204 No Content: a server MUST return a 204 No Content status code if a deletion request is successful and no content is returned.
- 27. CREDITS ▸ JSON API Specifications: http://jsonapi.org/format/ ▸ Escaping the Bikeshed with JSON API: https://www.infoq.com/presentations/json-api ▸ The Bikeshed Anti-Pattern: https://wiki.hackerspaces.org/The_Bikeshed_Anti-Pattern ▸ Why Should I Care What Color the Bikeshed Is?: http://bikeshed.org ▸ Pragmatic design with JSON API: https://jeremiahlee.com/blog/2017/10/10/pragmatic-design-with-json-api/