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
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 is a community-driven specification for building APIs and formatting API responses.
Another community-driven convention is Core API.
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 for your API's intended 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:
|201||Created||Creating a new resource|
|204||No Content||Either updating or deleting a resource (when no response body is returned)|
|301||Permanent Redirect||Used frequently for SEO purposes|
|302||Temporary Redirect||Used when content is temporarily not available on the site and the page redirected to another page|
|304||Not Modified||Used for referencing cached resources|
|400||Bad Request||General error in the request|
|401||Unauthorized||Incorrect or invalid authentication|
|403||Forbidden||Requester is not allowed to view the resource|
|404||Not Found||Resource was not found|
|409||Conflict||Trying to create a resource that already exists|
|500||Internal Server Error||General server error|
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 build better 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.