The Next Step to Build Better APIs — Consistent Data Structure

By Andrew Turner

You don’t build good APIs through coding alone. Like any other part of your business, APIs are best when they are developed as part of a detailed, end-to-end strategy. However, there are multiple parts of a comprehensive strategy and understanding each piece is essential to building better APIs.

In our first post about APIs, we talked about the need for a documentation-first strategy and how 3 main tools can help you build more effectively.

The next natural step in the process is to choose an appropriate data structure formatting convention for API endpoint responses and ensure it is applied consistently — here’s how.

UNDERSTAND YOUR API USE CASE

We talk a lot about “starting with the why” for product development — starting small discovery projects and using design thinking to get to the heart of the problem your product will solve.

Understanding the “why” is also an important concept when building APIs.

The key is to determine your API use case. Is the API for a mobile app? Is it for front end use? Will it be public for third party developers? The “why” of your API will help you choose the right data structure convention for development. However, there are many different options to choose from.

COMMON API RESPONSE FORMATTING CONVENTIONS

Navigating the various conventions for formatting API data structures might seem overwhelming at first. Here are a few of the more popular data structure conventions to consider:

JSON API

JSON API is a community-driven specification for building APIs and formatting API responses.

EmberData

Ember is a framework for creating ambitious web applications. If you’re building an API for an Ember application, you may want to consider using the EmberData convention for your API responses.

Core API

Another community-driven convention is Core API.

Flat Response

This is a simple and straightforward way to format your data structure that simply returns the data requested without a namespace object. Twitter and GitHub are popular APIs that follow this data structure formatting convention.

Seeking the pros and cons of each data structure convention seems like a logical next step once you’ve listed your options. However, there is no single correct data structure convention. You should choose a convention based on what is pragmatic and intended for your API use case.

It’s possible that a specific data structure convention would work best for your API’s use case — for example, Vinli’s need to return telemetry data could command a different convention than a project management API that returns tasks and project updates. Generally, though, keeping your data structures consistently formated will result in a better API.

When you establish your data structure convention from the outset of your project, you can better coordinate the “why” of your API and the way you’re building it. Then, you can include the data structure convention in your documentation and use Dredd to validate its use throughout the project.

After you establish a formatting convention for your API’s data structures, you should implement meaningful HTTP status codes to ensure your API responses are accurate.

STATUS CODES SHOULD ACCURATELY REFLECT YOUR API RESPONSE

As you use Dredd to validate your data structure formatting, make sure you use the appropriate HTTP status code for each type of response. However, because there are so many HTTP status codes, it is important to pay attention to the right ones throughout your development process.

At a higher level, there are 4 main HTTP status code categories:

• 200 Level: The HTTP 2xx codes convey successful responses.
• 300 Level: HTTP 3xx codes are reserved for redirects.
• 400 Level: This block of codes conveys errors that originate on the client side.
• 500 Level: Similar to the 400 level codes, HTTP 5xx codes translate errors, but on the server side instead.

To give you a better idea of the specific codes any engineer should know, we’ve compiled a list of the most important ones:

By using these meaningful status codes, you can avoid sending 200 level status codes when your API is returning an error! You want your API to be predictable and easy to work with — ensuring status codes match the true API response is essential to building a better API.

THERE’S MORE TO APIS AND PRODUCT DEVELOPMENT THAN CONSISTENT DATA STRUCTURES

You won’t be able to build an effective API without proper documentation and consistent data structures. And you won’t be able to succeed with digital transformation projects if you can’t buildbetter APIs. However, there’s much more to digital transformation product development than just APIs.

If you want to learn more about the product development process and how your better APIs fit into the bigger picture, download our free End-to-End Product Development Guide and discover how we combine business and innovation consulting, user experience design, software engineering and hardware engineering to create products that users love.

Originally published at https://by.dialexa.com/consistent-data-structures-the-next-step-to-building-an-api.

At Dialexa we start by asking “Do you know what your business will look like tomorrow?” Whether you have a plan, a problem or no idea, connect with us to explore the right answers for you.