See the related blog post I wrote: https://www.wlangiewicz.com/2017/06/18/designing-apis-json-api-specification/

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