Ruby Video
Talks
JSON API
Marco Otte-Witte
1 talk
#json-api
#api-design
#ember-js
#ruby-on-rails
#hypermedia
#rest-api
#developer-experience-dx
Summarized using AI

JSON API

by Marco Otte-Witte

In this talk at RubyDay 2015, Marco Otte-Witte discusses the JSON API specification, its importance, and its structure. JSON API serves as a standardized way to build APIs using JSON, aiming to reduce variability in RESTful API implementations. Key points covered include:

  • Purpose of JSON API: It addresses the inconsistencies in JSON APIs that make client code reuse challenging by establishing a common set of rules.
  • Historical Context: The specification originated from a conversation between Yehuda Katz and Steve Klabnik at RubyConf 2013, focusing on the ease of defining API formats for Ember Data.
  • Inconsistent Implementations: Otte-Witte highlights examples from APIs like GitHub, Travis, and Twitter, showing how different structures complicate integration and learning.
  • Core Structure: JSON API defines resource objects with specific keys like 'data', 'type', and 'attributes', making API responses predictable.
  • Relationship Handling: Relationships between resources are managed through a dedicated 'relationships' key, allowing for efficient data retrieval.
  • CRUD Operations: The specification outlines clear routes for creating, reading, updating, and deleting resources, maintaining consistency across requests and responses.
  • Performance Features: Advanced capabilities like including related resources in a single request and filtering responses enhance efficiency.
  • Conclusion: Otte-Witte advocates for JSON API due to its time-saving benefits and improved integration capabilities, emphasizing its use in his own projects. He encourages the audience to consider implementing JSON API for their API development needs, aiming for simpler and more effective systems.
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!
Edit
Explore all talks recorded at rubyday 2015
+2