JSON API Specificiation
0 likes159 views
The JSON API specification, published in 2015, outlines how a RESTful API should function, including URL structure, request and response formats, and error handling. It emphasizes an API-first approach, discouraging unnecessary workarounds, and covers aspects like HATEOAS for hypermedia links. While suitable for larger projects with diverse clients, it may not be ideal for smaller projects or internal APIs.
![case class Author(id: UUID, name: String, dateOfBirth: DateTime, dateOfDeath: Option[DateTime], createdAt:
DateTime, updatedAt: DateTime)
def toJsonapi(author: Author) = {
ResourceObject(
`type` = author.`type`,
id = Some(author.id),
attributes = authorAttributes(author),
relationships = authorRelationships(author),
links = List(Links.Self(selfLink(author))
)
}
def authorAttributes(author: Autor): Map[String, String] = { … }
def authorRelationships(author: Author): Map[String, Relationship] = { … }
def selfLink(author: Author): Link = Link(“/v1/author/${author.id}”)
13](https://image.slidesharecdn.com/jsonapispecification-170704125101/85/JSON-API-Specificiation-13-320.jpg)
![JSON Schema
● A formal description of the JSON document
● Imposes restrictions about contents of the document and it’s structure
● Example (UUID):
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}
14](https://image.slidesharecdn.com/jsonapispecification-170704125101/85/JSON-API-Specificiation-14-320.jpg)
JSON API Specificiation
- 1. JSON API Specification Wojciech Langiewicz, https://www.wlangiewicz.com 1
- 2. JSON API ● Specification published in 2015: http://www.cerebris.com/blog/2015/06/04/jsonapi-1-0/ ● http://jsonapi.org/format/ ● No large company behind it 2
- 3. What is JSON API? Document describing multiple aspects of how RESTful API should behave 3
- 4. What’s Covered By Specification? ● URL Structure ● How request should look like ● How response will look like ● How to perform server-side includes (fetching multiple related resources) ● How to publish and update documents ● How to handle errors 4
- 5. JSON API And Hypermedia ● HATEOAS - Hypermedia as the Engine of Application State ● Server can provide dynamic links ● Each of the links can have a meaning attached ● No need to hardcode URLs on the client side ● Clients can adapt to: ○ Contents of the response ○ Links returned which might allow them to traverse relationships 5
- 6. Motivation For Using JSON API Spec ● Anti-bikeshedding ● Formal specification and validation ● API-first approach 6
- 7. Bikeshedding Technical disputes over minor, marginal issues conducted while more serious ones are being overlooked. The implied image is of people arguing over what color to paint the bicycle shed while the house is not finished. Source: http://www.urbandictionary.com/define.php?term=bikeshedding 7
- 8. Formal Specification And Validation ● Documentation always up to date ● JSON Schema ● Validations 8
- 9. API-first Approach ● Design your API before implementing ● Prepare examples of requests and responses ● Validate examples against API Schema ● Replace examples with real implementations 9
- 10. Demo Time 10
- 11. Tooling ● Libraries ● JSON Schema 11
- 12. JSON API Libraries: Example Scala Library ● https://github.com/zalando/scala-jsonapi ● JSON API spec with Spray, Play! or Circe ● Example: https://github.com/zalando/scala-jsonapi/blob/master/src/test/scala/org /zalando/jsonapi/json/ExampleSpec.scala 12
- 13. case class Author(id: UUID, name: String, dateOfBirth: DateTime, dateOfDeath: Option[DateTime], createdAt: DateTime, updatedAt: DateTime) def toJsonapi(author: Author) = { ResourceObject( `type` = author.`type`, id = Some(author.id), attributes = authorAttributes(author), relationships = authorRelationships(author), links = List(Links.Self(selfLink(author)) ) } def authorAttributes(author: Autor): Map[String, String] = { … } def authorRelationships(author: Author): Map[String, Relationship] = { … } def selfLink(author: Author): Link = Link(“/v1/author/${author.id}”) 13
- 14. JSON Schema ● A formal description of the JSON document ● Imposes restrictions about contents of the document and it’s structure ● Example (UUID): "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } 14
- 15. JSON API Problems ● Generic API ● Weird Workarounds ○ Actions ○ Image Upload ● Slower Pace of development 15
- 16. Generic API ● API serves many different clients OK (just OK) ● Not able to add specific operations for specific clients ● Some clients need to perform workarounds or unnecessary requests ● But at the same time our API doesn’t get skewed towards specific clients 16
- 17. Weird Workarounds: No Actions ● JSON API requires you to abandon “Actions” ● But you might need to compensate for it by working around the model 17
- 18. Weird Workarounds: Image Upload ● Standard thing expected by a lot of clients ● No support for it because of media type limitations ● Workarounds: ○ Base64 encode images and send them as JSON attributes ○ Use API server only as way to get “Image Id” - client will upload image somewhere else ○ … 18
- 19. Comparing JSON API To Alternatives ● GraphQL ● Swagger / Open API ● RAML 19
- 20. JSON API vs GraphQL ● http://graphql.org/learn/ ● Alternative to JSON API ● Different approach to querying and results ● Query describes the structure of the document you are requesting ● Server side includes work by creating recursive tree structure 20
- 21. Swagger / Open API/ RAML ● Complement JSON API by having structure around documentation ● My suggested approach is to: ○ Design your API according to (JSON API) specification with JSON Schema ○ Use Swagger or RAML at the same time to give your API documentation a structure ○ Generate pretty HTML documentation out of RAML or use automatic Swagger tool to do this 21
- 22. Where To Use JSON API? ● Larger projects with long lifespan ● Multiple clients with different use cases 22
- 23. Not So Good Use Cases ● Small projects or with short lifespan ● Internal APIs ● APIs dedicated to single client 23
- 24. Summary ● Implementing JSON API requires more work ● “Thinking in resources, not actions” ● Good specification in cases of larger projects ● For smaller projects consider RAML/Swagger 24
- 25. Thank you! Wojciech Langiewicz, https://www.wlangiewicz.com 25