Building Efficient APIs with JSON-API

GORUCO 2018: Building Efficient APIs with JSON-API by Rushaine McBean

GoRuCo 2018

00:00:14.690 Hi everyone! I want to thank the organizers real quick before I get into this. This is my third GoRuCo and my first time speaking here, so it's really great and bittersweet to be speaking even though it's the last one. About me, I’m Rushaine McBean. I'm a software engineer and I write a lot of JavaScript and Ruby code. Currently, I'm an engineer at Kickstarter, a crowdfunding platform that brings creative projects to life.

00:00:28.470 As Luke mentioned, I'm an organizer of ManhattanJS, a monthly meetup happening in different startups across the city. We were recently at Newsela. We’re also part of a family of meetups. If you’re in Brooklyn, check out BrooklynJS; if you’re in Queens, you can find QueensJS; and for New Jersey, there's JerseyScript. You can also find me on the internet on Twitter or Instagram at @copacetic_kid if you'd like to keep in touch.

00:01:02.879 Today, I’ll be speaking about building efficient APIs with the JSON API specification. APIs are something most of us interact with on a daily basis. Whether we are consuming an API we've created within our applications, or interacting with a third-party API like Google Maps, we also construct them internally for our clients and mobile apps. We typically spend a lot of time designing what an API might look like and figuring out the best ways to design it. Unfortunately, sometimes that doesn’t turn out well for the end users consuming it, as it may lack clarity on how to interact with it.

00:01:39.270 Developers strive for productivity when coding, especially in interactions with APIs. That’s where the JSON API specification comes in, which delineates how clients should request or edit data from a server, and how that server should respond to those requests. Its main goal is to optimize HTTP requests, particularly in terms of reducing the number of requests made and the size of the data returned.

00:02:00.000 One way to begin optimizing is by using the correct content type so the server knows that it is receiving a JSON API request. The document structure is essentially a JSON object that will contain the keyword "data" at the root. From there, you will receive your top-level items that you interact with. The response may also include keys for "errors" and "meta", returning the corresponding information; this is illustrated in the example structure I will show you.

00:02:52.440 For resource objects, they typically have the ID and type. For example, if I use an article as a resource type, the ID might simply be a number. The resource usually contains attributes representing each field, analogous to columns in your database table, relationships, and relational data. This is often returned based on your request, containing links for associated resources. In compound documents, you'll have the related data side-loaded when requested, which looks like this in the JSON structure. Additionally, you'll receive keys to locate the information and any meta-data that conveys non-standard information relevant to your request.

00:04:09.720 When it comes to fetching data, it looks similar to standard RESTful practices. The top of the next section shows how to retrieve a collection. The second part gives you a way to get a specific resource. The third shows how to look up the author of the first article, allowing you to traverse that relationship. You can also independently retrieve relationships by using a specific endpoint for them.

00:05:35.110 When working with sparse field sets in a request, similar functionality to GraphQL is available, allowing you to specify only the fields you want from a particular model. Thus, you could query for specific attributes of an article, such as the title or body, while similarly customizing associated queries. Various sorting capabilities can be applied but often, developers prefer handling sorting on the client side.

00:06:40.040 You will also interact with regular CRUD actions using POST requests to create resources, which often involve specifying relationships in the process. Updating relationships can be achieved with PATCH requests, which enables you to pass along particular fields needing updates, encouraging a bulk update approach while maintaining the integrity of the data.

00:07:32.590 For delete operations, you generally use standard delete requests. The specification also provides a structured way of error handling, returning an object with an identifier, details, and the source, which helps identify the issue while displaying relevant messages back to users.

00:08:07.310 The JSON API spec has been around since its first release in 2015 and has been implemented in several languages, including Ruby and Ruby on Rails. Specifically, I've been utilizing the JSON API resources framework, which streamlines the process of adding functionality to your controllers, allowing them to respond to these requests efficiently while still offering options for customization.

00:09:12.150 Now, you might wonder why consider using GraphQL when JSON API already provides ample benefits. JSON API allows you to achieve similar outcomes without imposing multiple requests and presents less of an infrastructure challenge for teams that have already implemented it. Currently, there’s ongoing discussion within the community regarding enhancements needed to catch up with GraphQL features, such as deep querying and enhanced schema descriptions.

00:10:04.200 If your team is aiming for improvement in how they write their API endpoints, I encourage considering JSON API. It can represent a less demanding transition when modifying existing applications, fostering team alignment around certain conventions, and simplifying interaction with nested resources. If you have any further questions, feel free to reach out to me or ask me in person. Thank you!