09:00 - 17:00
API design can be challenging: There are countless styles to encode the data – which to follow? Clients want to fetch all data they need in a single request – how to support it? Concurrent write requests cause conflicts – how to mitigate? Luckily, you do not have to solve all problems on your own. Instead, you could build on top of well-established tools and standards like GraphQL or the JSON:API specification. JSON:API is a standard for building REST APIs. It supports advanced features like polymorphic relationships, HATEOAS and partial updates – without overcomplicating simple use cases. By providing solutions for common problems it enables teams to focus on the product they are building. In this workshop, you will gather a deep understanding of common REST API design problems and learn how the JSON:API specification solves them. You will notice that core benefits of GraphQL could be achieved within the REST architecture. By solving practical challenges, you will get hands-on experience with it. The workshop will not only give you a tool at hand to speed up the development of your next API, but it will also boost your knowledge about API design in general.
Content & Process
In the workshop we will discuss several problems of REST API design and learn how the JSON:API specification solves them:- Self-describing payload*: In some scenarios hard-coding the attributes and relationships of a resource in the consuming client is impractial. How to encode the data so that the client can derive a basic schema programmatically?
– Inclusion of related resources*: Forcing a client to do multiple requests one after each other to fetch all data needed (under-fetching) could harm application performance significantly. How to enable a client to fetch a resource and its related resources, a graph of resources, in a single request?
– Avoid over-fetching*: Often a client only needs a subset of all attributes of a resource. How to allow a client to fetch exactly the required data and avoid sending unused data over the wire?
– Reduce database workload*: A client should be able to fetch related resources later when needed. But providing the IDs of all related resources just in case could have significant impact on database workload. How to reference related resources while avoiding the lookup of their IDs in the database?
– Structured errors*: A client needs to know what got wrong in case of an error to help the user resolving an error or at least providing a helpful error message. How to structure and standarize error responses so that a client can process it programatically?
– Conflict mitigation*: Concurrent requests to update a resource can lead to conflicts. How to reduce the likelihood of such conflicts?
– Developer productivity*: Implementing REST APIs can require a lot boilerplate. How to support advanced features without slowing down development?
– What is the JSON:API specification?
– Encoding schema
– Fetching data
– Inclusion of related resources
– Sparse fieldsets
– Creating resources
– Updating data
Concurrent requests and conflict
– Deleting resources
– Implementing a JSON:API
For each topic we will:
1. Understand the problem of REST API design we are trying to solve.
2. Learn how JSON:API solves the problem.
3. Get hands-on experience by interacting with a JSON:API in a practical challenge.
After participating in the workshop you will be able to
1. understand common challenges faced when designing REST APIs and have a solution at hand,
2. make informed decisions if the JSON:API specification is the right tool for the job and
3. implement and consume a JSON:API following best practices right away.
Audience & Requirements
You should have a HTTP/REST client like Postman or Insomnia installed. Please familiarize yourself before the workshop with doing simple HTTP requests with it.
You should have experience writing and/or consuming REST APIs. Knowledge of REST API design is helpful but not required.