Use a (JSON) Schema for the Interface Portion of your RESTful API

RESTful APIs are never built for the sake of it, but always have a consumer in mind - and hopefully many consumers over time.

When looking at integrating with someone else's API, I've seen stats before that indicate that most of the time taken to integrate is due to understanding how the API works and what parameters, headers, and request formats are required.

Fortunately lots of folks are documenting their APIs, either through separate API developer portals or through a machine-parseable format like OpenAPI, but it's not everyone, it's not always up-to-date, and it also doesn't always include the full request/response formats.

Since OpenAPI 3.1, you can now link out to JSON Schema definitions for describing the format of the request/response entities. JSON Schema is a great standard for providing a machine-parseable, but more-technical-human-readable, definition of how your data interchange format needs to work, and it's great to have it as a first-class citizen.

As well as just generally having something documented for your API's models, the schema being machine-parseable means that there are some great tools around it to make sure that the schemas work correctly. In the Java world, we have a couple of good options that I've written about before. There's also which provides a hosted version of an NPM package that supports multiple languages, and is very neat, as well as a number of others listed on the official JSON Schema website.

I'd very strongly recommend getting started with this as soon as possible.

On a new project, it's straightforward to do because you are starting from a blank slate, so can look at creating the models through this means. It can also help if you're working in an API Design First manner, producing an OpenAPI document first, discussing with your consumers, and then starting work on your API, but doesn't need to be.

But when you've got an existing (pre-loved/legacy) system, how can you retrofit this? Fortunately there are also some tools out there that can convert your existing models to schemas which can take some of the hard work away, but I'd say that if you can get good test coverage of the existing models, it's fairly straightforward to retrofit it.

For example, see this small-scale migration on a project at work. We've had to make a few changes as things are a bit stricter with the new schema, but the structure of the objects are exactly the same, and our tests validating that still work.

As a consumer of APIs, it's much easier to be able to integrate when you have a set of schemas available, as you can generate the models you need to utilise, confident that they'll work as they're (hopefully) being utilised in the same way on the server-side.

There are also other options besides JSON Schema that you can use, I just recommend it as it's a commonly used and well supported format for RESTful APIs.

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#api #json-schema #rest.

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.