00:00:14.000
Hello everyone, I'm going to talk about JSON API. I'm Marco Otte-Witte, and despite my Italian name, I'm actually from Munich, Germany. I founded Simpls, an engineering consultancy based in Munich.
00:00:20.160
We work with a variety of technologies including Ember.js, Rails, and recently, Phoenix. You'll also see that Ember Data plays an important role in the history of JSON API. I brought some stickers from our local Munich Ember.js Meetup, which you may have already found in your bags.
00:00:36.000
I also wanted to announce that we are organizing an Ember.js workshop in Berlin in January. You can use the discount code if you're interested in attending the workshop.
00:01:02.160
So, what is JSON API? JSON API is a specification for building APIs in JSON. This talk focuses specifically on that specification, which is simply called JSON API. They took a very generic name and decided to use it for this purpose.
00:01:14.880
Interestingly, the logo of JSON API is missing quotes, which makes it invalid JSON. I think Steve Klabnik, one of the core maintainers, mentioned that this is an Easter egg, and he finds it quite amusing.
00:01:30.640
But why is a specification for building JSON APIs even needed? A noted figure questioning this is Thomas Fuchs, a former Rails core team member. He does not seem to support the idea of having a specification, and while I respect his perspective, I do not agree with him on this issue.
00:01:56.320
The main reason for having a specification like JSON API is that RESTful JSON APIs can vary widely in implementation. This inconsistency makes it hard to reuse client code, as each project may require rebuilding serialization and validation from scratch, or at the very least, adapting them to fit different structures.
00:02:36.280
Let me show you some examples. In the GitHub API, when you fetch a repository, you receive a flat object without a root level. However, if you fetch the same repository from Travis, you get a root-level key, which is quite a significant difference. It complicates reusing code since the responses' structures differ.
00:03:14.760
Similarly, with Twitter, the URL structure does not follow standard conventions, making it difficult to integrate. For instance, the way relationships are structured in API responses is also inconsistent. This inconsistency leads to extra overhead when learning new APIs, as each one usually follows its own set of rules for structuring documents.
00:04:03.240
When building and using these APIs, discussions about structures arise, such as whether to include a root object or how to handle relationships. These discussions are often lengthy and are known as 'bike shedding,' a term that refers to how teams can spend significant time on trivial matters, rather than focusing on what's truly important.
00:05:14.560
The idea behind JSON API is to minimize these trivial discussions, allowing developers to concentrate on implementing their systems. In terms of history, it started with a discussion between Yehuda Katz and Steve Klabnik during RubyConf 2013, where they aimed to make it easier to define usable API formats for Ember Data.
00:06:09.640
The first draft of JSON API merely documented what Active Model Serializers and Ember Data had already been doing. Since then, it has evolved significantly and is now maintained to ensure future compatibility.
00:06:43.360
JSON API aims to define a broad media type that supports numerous use cases, specifically when exposing and consuming resources via HTTP. It doesn't aim to dictate how arbitrary actions should be handled on client-server interactions. Adoption is vital, so it strives to be user-friendly and similar to existing frameworks, making implementation straightforward.
00:08:07.760
It also emphasizes human-readable formats for easier debugging and project understanding. Let’s discuss the actual format of JSON API without going into exhaustive detail. The core part defines resource objects representing individual resources like blog posts, which are typically structured with a 'data' key that holds the primary data.
00:09:42.600
When you retrieve a single resource, the response structure contains: the 'data' key, resource type, resource ID, and relevant attributes. If multiple resources are fetched, the response will still have a 'data' key containing an array of resource objects.
00:10:56.080
Relationships are also included in the response format under their own 'relationships' key, which can further define the structure of individual links, ensuring clients can correctly utilize and interpret the data.
00:11:43.720
The specification also allows for hypermedia options within responses, giving flexibility to choose whether or not to include additional links or data. This opt-in feature can help manage relationships more effectively.
00:12:51.760
Another key aspect is the ability to include related resources in a single request, alleviating the issue of making multiple requests to gather related data. This way, a single network request can return all relevant resource data without causing performance overhead.
00:13:41.680
CRUD operations have defined routes matching expected behaviors in standard RESTful patterns. You can create, fetch, update, and delete resources while adhering to a consistent structure in requests and responses.
00:14:54.720
The responses are structured similarly to the requests; when creating, the client omits the ID, as it's assigned by the server. For updates, similar procedures are followed, allowing for efficient backend interactions while ensuring correctness of state.
00:16:59.200
It also includes advanced features like filtering which related resources to include in responses, allowing for efficient strategies when reading large sets of data without overloading the client with unnecessary information.
00:18:32.560
In wrapping up, I highly recommend using JSON API. I have seen it save a great deal of time, reduce friction within teams, and improve integration with clients. We consistently utilize it in our projects due to its clear benefits.
00:20:48.080
Thank you for your attention, and I hope you find JSON API useful in your own projects!