5 best practices for managing or creating your APIs

Why do you need to think of API as a product?

These internal technology assets have the potential to be the revenue-generating assets of tomorrow. But how do you make your APIs valuable? You have to create and use them as if they were a product:

Responding to A NEED

• To ensure that APIs will create value from the start, it is essential to create them as demand-driven products – a demand that is willing to pay to use the product and therefore provide a good user experience.

Know the developer

• Take an outside perspective and think more about the needs of your target users. For example, what style of API design do your consumers prefer? Is it REST, GraphQL, or a mix of both? If you build an API program without considering the needs of your target audience, it may not see the light of day.

Adapt to future needs

• The API is key to using a platform at scale: it's easy to get started with a product by using its interface and managing it by hand. As customer needs grow, it is essential to be able to automate without having more users to handle it. Thus, the UX that could attract at the beginning becomes DX, essential to growing.

Develop your API as a product

• As it is possible to monetize an API in addition to its main product (or even only through an API), it is necessary to consider it as a product in order to treat it, in the team, as a product: with its own dedicated team, its own budget, particular attention to DX, its own marketing, etc.

How to choose API Design Standard?

If you don't know where to start, here are the basic rules to create and choose an API that will last over time:

Understanding the API

• Following a standard allows users to quickly understand how an API works without necessarily reading the documentation, and thus instinctively understand how it works. The goal of an API to be standard is to be readable and to be able to read the API of others. To know if it is easy to use, you can look if the endpoints are precise, concise, and simple.

Easy access

Documentation:

The documentation must be accessible and complete. 

Look for an OpenAPI (ex Swagger) file, which mean this API is following standard methods.

Authentication:

API Key is the simplest to use, OAuth 2 is the more secure but will be more technical for your users.

Developer experience:

The best is to have interactive documentation with the possibility to generate test requests.

And SDK available in many languages is nice to have. If you have already an OpenAPI file, it's possible to generate them automatically.

The simple use of the API

Think about “how” the API is going to be used, by which users or automated services so that you never have something too complex for quick adoption.

You also need to think about the tools and capabilities of the customers to program their requests. If they are too complex, they will have difficulty launching them and therefore using the API.

Good respect for the simplest standards ensures good compatibility. Is there rate-limiting? Is it flexible enough for my use?

What are the authentication options for my API?

As seen before, authenticating an API is one of the keys to easy and quality use for you and your customers, so which solution should you choose?

Tips and essential questions

Follow the standards of authentication: no need to be creative or innovative on this part. The aim is to be used by most users and integration systems. Go with an API key inside a header (and/or a query parameter) or a Bearer Token (inside an Authorization header) are among the most used methods.

Documentation and an example of how to authentication request is a must-have.

Good practice for API keys management:

• Easy renewal of an API key (for key rotation in case of a leak)
• Only show the key once, this ensure a better security
• Ability to generate multiple API key (one for each users for example or by apps)
• Ability to generate key limited to specific action (read-only, read-write, admin for example)

Embrace OAuth2 if you can: that'll give to your users more control and more granularity with permissions.

How to manage the monitoring of my API?

We often think that everything will work without problems and forever, so how to manage the stability of its integrations? What tools to use, what are the standards, what solution to prevent your customers, and how to know if your API is always stable?

Measure performances:

Measure the average response time and measure the 95th percentile: see if the measured times are in line with the functioning of the platform. The ideal is to be under 200ms for the feeling of “real-time” and 100ms for the feeling of immediacy.

The 95th percentile says that 95% of the time, the usage is below this amount: so, the remaining 5% of the time, the usage is above that amount.

Errors management: 

You should ask yourself:

• Did I manage the errors in my code well?
• Are the errors caught?
• Have I customized the errors I present to my users?

Don't forget to add a full error message, some context, and an error code. That'll help your users to be autonomous and figure out what's going on.

Make sure the API responds with the right HTTP errors and does not have 500 “generic” errors with messages in them.

Some classic errors to use inside your API:

Main errors:

• 401/403 (authentication failed),
• 404 (it doesn't exist),
• 408 (if the request has exceeded an allotted time),
• 409 (if there is a conflict with a request),
• 503 (if the service is down) in addition to the usual 400 and 500.

If other 400 or 500: use customized messages.

Behaviors to avoid:

Never send a 200 code response with the error message inside. 2xx code response is for success only.

Notifications:

Take into account how the team is notified and, above all, how the errors are handled by the team: this is to be managed after the monitoring, but these are good questions to ask because, beyond the tools, there is the subsequent management by the team of the information reported.

What is the best way to create a good documentation for an API?

To create a quality document, here are some points you need to make sure:

Don't reinvent the wheel and use great documentation tools:

You have many great documentation systems, some open-source (like Docusaurus, Redoc, Slate) and some commercial (Stoplight, Bump.sh, ReadMe, Gitbook) to do it.

Stick with some that allow you to import a standard specification file like Swagger or OpenAPI: that'll give you more freedom, a common file for collaboration and you'll be able to leverage all others tools on this standard (take a look at openapi.tools).

Make your documentation interactive:

Some tools allow you to generate snippets of code or even allow users to run tests requests (like Swagger UI). That will help your users a lot by figuring out how the request should be formatted and to test without having to start their own development environment for testing a request.

Maintain a changelog:

Maintaining a changelog is a great way to inform your users of any change. It's the best if you have the capability to inform your users on any change: you'll be able to release new features with confidence and with potential feedbacks from your users.