DEV Community: FabriceMk

Guidelines to build good RESTful APIs - Part 4: Ops, Ops, Ops! and Final Word

FabriceMk — Sun, 07 Mar 2021 07:16:19 +0000

This current post is the last part of a 4 articles series about our Guidelines to build good RESTful APIs.

You can access the other articles from the following links:

Part 1: Introduction and Design Phase
Part 2: Implementation Phase
Part 3: Testing Phase
Part 4: Ops, Ops, Ops! and Final Word - You are reading this 😀

🛠 "Ops, Ops, Ops"

We finally reached the last part! I wanted to talk a bit about operations, especially the ones related to infrastructure and monitoring. Because now that you have the code and the tests, you need to host it somewhere and you want to make sure it continues to run well.

🌎 Have proper environments

We use several environments for our development process:

DEV to push the latest changes by the developers and do initial testing and validation.
STG to execute more complete tests (QA Regressions, Performance, Security, Reliability etc...) with a version of the code we would like to push to PRD.
PRD serving the application to the end-users.

Some teams may have more (like pre-release, alpha, beta etc...) but in our case those 3 are usually enough.

We are working with flexible Cloud infrastructure so not everything may be applicable to you but here are some properties of our environments:

Extensive of use automation and Infrastructure as Code. We have Shell scripts, dedicated deployment servers like Octopus Deploy and we make use of Terraform when possible.
- Creating environments manually has a LOT of pitfalls. It's difficult to repeat, more error-prone and it's easier to introduce inconsistencies. You can play around for prototyping with a sandbox environment but once you want to create a proper DEV, try to immediately automate as much as you can.
- Allows for easy thrashing and recreation of temporary environments that can be useful for some specific tasks or disaster recovery.
STG is as close as possible to PRD
- I have seen some STG environments that were totally different from their PRD counterparts. This defeats the purpose of STG altogether. It is supposed to "replicate" PRD so you can test with confidence before releasing. You end up having changes and operations that are PRD specific that cannot be tested and can lead to mistakes and ultimately downtime.
- It doesn't mean that STG has to be an exact copy to PRD all the times though. For costs reasons, we usually have STG as a shrunk down version of PRD most of the time. It has the same components but with less instances for example. But combined with the extensive automation we can easily scale STG to PRD levels for important operations like Performance Testing. And we can then shrink it down when not actively in use.
DEV is a cost-efficient environment that should be easy to recreate as it's the most unstable by nature. We don't hesitate to have databases running as containers instead of dedicated VMs for example. The size is small and we try to keep it to a single region when most of our STG and PRD are deployed on multiple regions or availability zones.

With the popularity of Docker, Docker Compose or Kubernetes, we try more and more to create entire environments on demand for Local and DEV so parallel features in development can be tested in their dedicated isolated instances.

🏗 Build Once, Deploy Anywhere

When you promote your application from one environment to the next one in your pipeline, make sure that you ONLY PERFORM CONFIGURATION CHANGES. The rule is to have the same code artifact across environments and just inject different configurations.

I have seen some build pipelines that perform a full rebuild of the entire application for each environment. It's not great as every time you build, differences that are outside of your control can sneak in:

A transitive dependency may have been upgraded if your package manager doesn't support full dependencies snapshots.
Your build toolchain has changed between 2 deployments (like a plugin or server upgrade).

By building only once, you remove the Code as a potential source of issue between environments and can focus on the Configuration or the Infrastructure.

🔃 Have a Deployment Strategy

I remember the old days of being an IT student and pushing my new website version by uploading and overwriting files directly with my FTP Client.

This should stay memories, don't do that on your production APIs please 😱

Having a proper Deployment Strategy is necessary to aim for "Stress Free" releases. It can help to:

Avoid downtime during the deployment of a new version.
Be able to rollback fast if a new version is causing issues.
Test a new version on real PRD infrastructure.

You can find more details on well-known strategies on the following link: Six Strategies for Application Deployment.

Your infrastructure may facilitate the implementation of some strategies. For example Azure App Services has easy Blue/Green deployments while Rolling Release is available out-of-the-box on Kubernetes.

🕵️‍♂️ Observability and Alerting

What's worse than having errors in Production? - Having to debug without any details about them.

The last thing you want when you are trying to fix your API in Production is to spend hours to even identify what is wrong. When developers work locally, they use various tools to find issues: debuggers, profilers or something as simple as a printf/console.log.

The goal is the same, having more insights.

This also applies to systems as a whole. If you have an issue on your API (it's becoming slow or unresponsive, it starts returning a lot of HTTP 5xx errors etc...) you need data to help you to find the cause. The 3 main types of data fulfilling that purpose are:

Logs like exceptions happening on the application level or errors outputs on the system level etc...
Metrics like the CPU percentage of VMs, the number of failed requests, the response time etc...
Traces like a waterfall view of a request going through different components.

I invite you to read the following article The Three Pillars of Observability

Developers need to ensure their application can generate logs in case of errors for debugging purposes. Various languages and frameworks have dedicated tools like Logs Managers. These logs then can be collected on some system that allows for consultation and ideally have search capabilities like ELK.

Cloud/Infrastructure providers and DevOps are more in charge of gathering metrics of the infrastructure and the different components. You need to be able to see if the traffic to your API is growing, if the disks of your VMs are getting full or if the CPUs are maxed out when receiving a spike of traffic.

All those data can also be used to set up triggerable alerts when some threshold or changes in behavior start to happen. Systems with proper alerting systems try to detect Production issues as quick as possible in order to minimize downtime. But they can also help to detect small hidden issues that can grow: if you start seeing the response time increasing release after release, you might want to scale or optimize some parts of your system before it becomes a bigger problem.

Final Word

That's it! You now have an overview of the general practices our team use and I hope it will help you to build better APIs.

But don't blindly follow any guidelines list you find on the net!

Each project has its own specifics and context. The goal was to provide a baseline you can then adapt or extend to your likings. Evaluate each item of this list and then you can decide which one to apply.

Guidelines to build good RESTful APIs - Part 3: Testing Phase

FabriceMk — Sun, 07 Mar 2021 07:14:05 +0000

This current post is the 3rd part of a 4 articles series about our Guidelines to build good RESTful APIs.

You can access the other articles from the following links:

Part 1: Introduction and Design Phase
Part 2: Implementation Phase
Part 3: Testing Phase - You are reading this 😀
Part 4: Ops, Ops, Ops! and Final Word

🧐 "Does it even work?"

Testing is an important step in our development lifecycle and we have different types of tests in every project. They all have their specificities so we try to have a balanced mix of all of them.

You may have seen this pyramid about testing:

Most of the time we follow this pattern with a lot of automated unit tests. As we move into integration and E2E tests the amount of tests decreases as it becomes more and more expensive to write and run them.

The priority of the tests depends on your project. For example when we inherit from an existing API with no tests at all, we prefer to focus on E2E and integration first as they are better to detect regressions on the "product behavior".

⚙️ Unit Testing

Reference: Wikipedia article about Unit Testing

In our team, unit tests are mandatory when building new web APIs. They are written and maintained by the developers.

They are the closest to the code and are tightly coupled with the language or framework you are using. As such they need to be also treated as code:

Aim for good quality. Avoid silly logic, name your variables properly, run linters on unit tests code!
Learn how to properly use the testing frameworks at your disposition. Testing frameworks are usually powerful but can be very complex at the same time. You should spend the appropriate amount of time to to feel comfortable with them.
Make good use of support helpers like mocking/stubbing or assertions libraries, efficient runners... They can dramatically help to have more readable or simpler tests.
They should be reviewed!

One note though: we noticed that trying to get rid of all copy-paste and have reusable functions for absolutely everything like the application code could lead to hard-to-read tests. That's why we often have specific coding rules (and linter rules) for unit tests that are a bit more relaxed. It's up to you and your team to find the balance that works well.

Pros	Cons
Find some problems early in the development phase (especially bugs and implementation flaws)	Cannot detect broader errors (created by the interactions of several components together)
Fast to execute	Can give a false sense of security if you rely only on them and on metrics like coverage (100% coverage =/= bug-free)
Helps a lot to be more confident during refactorings	Need to find a good balance between reusability and readability in the tests codebase
Can act as some type of documentation
Are automated by nature

🧩 Integration and End-to-End Testing

Those tests are mostly under the responsibility of our dedicated QA team. They test bigger chunks of the codebase/product at the same time and have higher value when we test the overall product.

The QA team usually comes up with test scenarios once the products specs are done. The developers then review those scenarios and give feedback to QA engineers from a different point of view. It also helps the developers to better understand the test suites and anticipate issues when they change some parts of the implementation.

Pros	Cons
Cover test scenarios closer to real use-cases and product specs	Take more time to implement and automate
Can be compared directly to specs	Slower to execute
High-value to detect product regressions	Don't cover everything and focus only on the main flows
Can also act as some type of documentation

🏎 Performance Testing

The APIs our team builds are mainly consumed by mobile applications and may have to serve up to several tens of millions requests per day. Some of those APIs also have to deliver important content for the applications to work properly: API performance needs to be tested.

Before the initial release of an API, we benchmark our different endpoints (with the help of specialized tools like Locust, Gatling or k6) in order to:

Measure the max capacity of our systems. How many requests/clients we can support and keep an "acceptable" response time.
Detect which components are the bottlenecks. Is the database slowing down everything? Are the connections pools properly configured? Is the Load Balancer big enough? etc... They may require immediate fixing/mitigation.
Study the scalability of the different components. How much more traffic we can sustain if we double the memory of that component? How are the infrastructure costs increasing with the traffic scale?

Those numbers are precious to evaluate the cost of the system at several scales, guarantee the response time for a specific number of clients etc...

Performance testing is not straightforward and requires a strict test protocol. It can also be time consuming. Not all APIs need it but ask yourself those questions:

"If our product becomes popular, will our systems scale? How easy and fast will it be? How big is the growth/financial/reputation impact if the system cannot sustain the traffic?".

If you work on such sensitive APIs, prepare and run Performance Testing before the initial release. Ideally, you want to monitor that performance continuously and make sure the performance doesn't degrade over time.

It's a big topic on its own but here are some resources that could help you:

💪 Reliability Testing

Reliability Testing aims to confirm how your system reacts when one or several components face different levels of degradation. As for Performance Testing, not every API needs it. But if your API is an important piece for the continuity of service of your business, you need to think about reliability testing.

During the design phase, the architect or the developers may introduce some redundancy like:

Having several instances of the web API so if one becomes unhealthy, the service is not totally down.
Having multiple database nodes like a Primary-Secondary failover setup, a triple-node cluster etc...
Deploy the service on multiple datacenters/regions/cloud providers to cope with geo-localized issues (regional disaster, power outage, network issue etc...)

That's very good! But in reality, things are rarely so simple:

Maybe you didn't configure the services properly to take advantage of that redundancy (some databases require that the code handle some aspects of the failover).
Maybe your supposedly "optional" cache layer breaks your entire application if it becomes unavailable temporarily.

What seems nice on paper needs to be tested in real conditions. You have to make sure all the mechanisms you put in place are working as expected in case of emergency. Similar to this famous quote about backups:

There’s No Point in Backing Up Your Data if You Don’t Test Your Backup.

You want to know if your API continues to work after the failure of some components.

How many requests will be dropped during the failover? Is it acceptable?

The testing is very specific to each project but try to figure out scenarios you want to confirm depending on the quality of service you need to guarantee.

🔐 Security testing

At Rakuten we are lucky to have teams dedicated to Cyber Security. They help us to test the software we build. For web APIs, it often involves Penetration Testing by using:

Source code scanning to detect vulnerable software versions.
Port scanning to detect vulnerabilities on the network stack.
SQL, XSS injections.

They can also help at the design phase to make sure you don't introduce fundamental business flaws that would require a major revamp later.

So problem solved? Not exactly.

Having dedicated security engineers is nice but software security should involve EVERYONE developing the product: the product specs, the developers, the QA and also the DevOps in charge of setting up the infrastructure.

The involvement of the different roles is important to apply the concept called Defense In Depth where multiple layers of security are in place to minimize the chances of attacks.

For every new API our team builds:

We go through a Security Audit.
And we make sure that all issues are fixed before release.

The ideal situation would be also to have some automated security diagnostics running against your APIs as part of the CI/CD pipeline and detect more issues by yourself as early as possible.

⏩ Next part

After testing you now need to deploy your API and make sure it runs properly at all time. Let's talk about operations in the final article.

Part 4: Ops, Ops, Ops! and Final Word

Guidelines to build good RESTful APIs - Part 2: Implementation Phase

FabriceMk — Tue, 23 Feb 2021 12:12:59 +0000

This current post is a 2nd part of a 4 articles series about our Guidelines to build good RESTful APIs.

You can access the other articles from the following links:

Part 1: Introduction and Design Phase
Part 2: Implementation Phase - You are reading this 😀
Part 3: Testing Phase
Part 4: Ops, Ops, Ops! and Final Word

✅ "Just Do It!"

Now that you have designed our API, it's coding time! I have selected a couple of good practices that can be applied independently of the language or web framework you may be using.

🍰 Layer your API

Except for Proofs of Concept or prototypes, layer your implementation from the start! You won't gain anything by not doing it.

Layering is a way to organize your code for separation of concerns and follows those rules:

Each layer depends on the layers beneath it.
A layer should have no knowledge about any layer above it.

Here is a layering we often use in our APIs:

The Edge layer (alternative names: Controller/Presentation layer) hosting the API Controllers, the various helpers and middlewares. It's the layer in contact with the requests from the clients.
The Logic layer (alternative names: Business/Application/Domain layer) usually implementing the business logic.
The Data layer (alternative name: Persistence layer) that handle the data persistence.

If we look closer, we realize that the nature of the code of each layer is different:

The Edge layer for example is usually tightly coupled to the web framework you are using. The way controllers, middlewares, validators are implemented can be vastly different between 2 frameworks even if they are written in the same language. It also handles a lot things related to HTTP requests and responses.

On the other hand, the Logic Layer is often made of plain objects representing your business entities and code taking care of manipulating them.

As for the Data Layer, you are likely to import and use clients that "talk" with specific databases, external APIs or some type of storage. And each usually come with their own specific and complex objects (the way MongoDB and MySQL represent and expose queries and results objects to you are totally different for example).

The benefits of layering are then more obvious:

Clearer scope for each layer in terms of role but also in terms of dependencies. It's unlikely that your Logic Layer will have to deal with HTTP Requests objects or HTTP codes for example.
Easier to expand or modify one specific part of your code without impacting the rest.
Improved reusability. For example, you can have multiple endpoints on the Edge Layer that use the same logic in the Logic Layer.
Clearer testability. A layer like the Data Layer is usually more difficult to unit test than the Logic Layer. But because they are clearly separated, you have a more comprehensive view of the testing status of each layer and may decide to rely on unit tests for the Logic Layer and more on integration tests for the Data Layer.

One of the reason given by developers that use the "kitchen sink" approach is that their API is not complex enough to require layering and it's a waste of time. I don't buy that, it takes literally a few of seconds/minutes to separate your layers. And naming is the longest part of it. Of course just creating a bunch of folders is not enoughs. You have to think where each piece of code goes and make sure it stays organized thorough the development but it can still be a lightweight process. But it's nothing compared to the hours of refactoring a "simple" API with all the codebase in the controllers can cause once it has evolved into a "spaghetti mess".

Key-points

Layering your codebase brings tons of benefits.

Layer from the beginning, it costs nothing.

👻 The power of abstraction

Even if a layer creates some degree of isolation, it still needs to communicate with components located in lower layers. This communication can become messy if not controlled properly.

A solution we use in our team is proper abstraction and clear contracts between layers.

The goal is to avoid leaking implementation details.

I'll take a simplified example of a Data Layer having to interact with a MySQL database with the following properties:

The Data Layer is using a third-party MySQL client MySqlClient to connect and perform queries to a remote MySQL database.
MySqlClient uses its own objects to represent results MySqlResult or errors MySqlError.

In a typical API, the Logic Layer needs to fetch data from the database in order to execute some business logic. And it instructs the Data Layer to do so.

A mistake would be for the Logic Layer to directly communicate with MySqlClient. Because it would then become tightly coupled to the underlying database: MySQL. The code in the Logic Layer would have to extract results from MySqlResultand handle MySqlErrors.

What happens if one day MySQL doesn't suit the needs anymore and we want to to change it to let's say MongoDB? We would have to change the Data Layer and all those MySQL related objects that leaked in the Logic Layer.

A solution would be to abstract your MySqlClient by something like DatabaseClient and have your custom and more generic DatabaseResult and DatabaseError. The Logic Layer would then interact with this abstract client instead of MySqlClient. That way, your Logic Layer becomes unaware of the real database you are using. And it's good as it doesn't care! It just wants the results and knows that errors can happen with the "database".

The other advantage is that the communication "contract" between the layers is less sensitive to changes. You better understand how the data flows between your layers.

I concede that you don't change your database everyday but this concept can be generalized to a multitude of other situations.

In the recent years, we had to migrate several of our databases hosted on Azure Cosmos DB to MongoDB and we were able to do it by just adding a new implementation class and making a small change of configuration in all the impacted APIs. Abstracting the Data Layer only took us a couple of minutes in the early stages of the project and saved us hours of refactoring of the Logic Layer code and its unit tests.

Key-points

Having clear communication contracts helps to understand the data flow between layers.

Don't leak implementation details especially between layers.

Abstraction makes the code more flexible to changes.

Abstraction reinforce the isolation.

Abstract from the beginning, it's not expensive.

🎣 Beware of your exception catching

I won't get into the details because exception handling is a rich topic but you have to know that unmanaged and non-consistent exception handling can become a huge source of issues in your API.

Keep the following rules in mind instead, they work quite well for us:

If you encounter an exception, catch it only if you can handle it locally. If not, it's better to let it resurface to the upper levels.
- Badly handled exceptions in the bottom layers can silence real problems.
- Don't catch and re-throw a more generic exception, you may lose important information.
- It's fine to wrap an exception with one of your own exception (but make sure you don't remove information in the process).
- In most cases don't catch and re-throw the same exception if you just want to log (see next point).
Have a general exception catcher on the Edge Layer that will catch any non-handled exception that managed to bubble to the surface. This is where you will be able to handle the logging in a centralized way and standardize error messages that are returned with HTTP 500 for example.

⏩ Next part

You have written all the code needed for your API to run. We now need to check it works properly.

Part 3: Testing Phase

Guidelines to build good RESTful APIs - Part 1: Introduction and Design Phase

FabriceMk — Tue, 23 Feb 2021 12:11:24 +0000

Introduction

I have been working on RESTful APIs for several years at Rakuten in Tokyo using various languages and web frameworks. Their size ranged from tiny single-endpoint micro-services to big and complex ones. And most of them had pretty decent quality.

But I also met some APIs that were much more difficult to work with. Not because the problem they tried to solve was complex, but because they all had accumulation of issues during their development. Issues that could and should have been avoided because they weren't proper thoughtful trade-offs.

Software development in a company has its own challenges, namely resources allocation, schedules and deadlines, business requirements etc... The key to build good quality APIs even with those constraints is to properly choose your battles.

For that reason I would like to share a list of practices our team tries to apply every time we build a RESTful Web API. We will go through the following development lifecycle and point the particular areas that require focus.

Note: for readability reasons, the article will be split into several parts and the links to each of them will be updated once they are published.

Part 1: Introduction and Design Phase - You are reading this 😀
Part 2: Implementation Phase
Part 3: Testing Phase
Part 4: Ops, Ops, Ops! and Final Word

🗺 "Does anyone have a plan?"

First, a reminder about typical properties of most APIs:

An API solely exists to deliver a SERVICE by being consumed by "clients". It is similar to services providers in real life, be it a shop, a restaurant, the postal services etc... You want to deliver a good service and the clients to be "happy". If you ever had to use and consume a third-party APIs in your projects, maybe you have experienced the following:
- I wonder if there is an endpoint to request multiple results in a single request instead of sending a lot of single result requests?
- Is it possible to filter the results? I don't need all these.
- Do I really need to provide all those hundred parameters that looks like they could be optional?
- I followed the example but I keep getting an error with no explanation.
- Where is the documentation?
- Why the naming is so inconsistent? It's confusing.

When you are the one building the API, you also want to ask yourself those same questions. You are not building an API for the sake of building it, someone will use it! It can be yourself, your teammates, another team in the company or even clients who are paying for your product.

Modifying an API Contract is HARD, especially if your API is public. Any change on your API behavior can break the clients and their applications (it can cause crashes and affect millions of users). In practice, an API will always have to evolve to a certain degree. There are techniques to manage these changes like API versioning or backwards-compatibility support, but it will always be a tricky exercise.

That's why you WANT to spend time on designing your API. It's the phase where you can create early mistakes that may have a huge impact on your API usability. Those mistakes are also often the most difficult to fix at a later stage. The time spent can vary depending on the size of the API, if it's public facing with a lot of clients etc... You don't need 10 hours of design for a throw-away API only used for some prototype but keep that in mind.

⚠ Make sure you understand REST

If your answer to the question "What is REST for you?"

is just "it's about using GET, POST and DELETE".

It's probably a good idea to refresh your memory a bit by reading the following article: https://restfulapi.net/.

It's well written and concise. You also have more details if you want to dig a bit deeper.

I insist on having solid fundamentals because REST has a lot of misconceptions about what it does and doesn't enforce.

For example and contrary to the popular belief, REST doesn't tell you which HTTP method (GET, POST, PUT, DELETE) you should use for operations as REST is not even technically tied to HTTP.

It is therefore more productive to know exactly the constraints of the REST architecture, work with them and know which parts of the design require you to take more complex decisions.

Key-points

It's bold but you NEED to know and understand REST to build good RESTful APIs.

Having solid foundations will let you focus on the more custom (and more interesting) parts of your design.

💦 Naming and endpoint structure is hard but there are good practices out there

When designing your API contract, the first difficulty is to come up with a proper hierarchy for your endpoints and NAME them.

REST asks you to organize your data around Resources but doesn't enforce any specific way to create a proper hierarchy.

A large number of people wrongly relate resource methods to HTTP GET/PUT/POST/DELETE methods. Roy Fielding has never mentioned any recommendation around which method to be used in which condition. All he emphasizes is that it should be uniform interface. If you decide HTTP POST will be used for updating a resource – rather than most people recommend HTTP PUT – it’s alright and application interface will be RESTful.

In practice, most of the public APIs follow some conventions considered as "reasonable". By following the same conventions, you help other developers to understand your API faster as they are used to see those patterns. Here is a very good (and short) list of some popular naming conventions:

REST Resource Naming Guide.

Among some of those naming guidelines:

Use nouns to represent resources: api/my-resource/, api/my-other-resource, api/my-resource/{id}/sub-resource
Avoid verbs especially if they are mirroring what the HTTP methods could perform (in an HTTP context): Avoid api/delete_my-resource and api/get_my-resource when you can simple have HTTP DELETE api/my-resource and HTTP GET api/my-resource
BE CONSISTENT! You don't want the same parameters to have totally different names in 2 similar endpoints.

I would lie if I say that every time we design APIs in our team everything goes well. We sometimes have "passionate" discussions and 2 developers may propose different designs that are technically correct and elegant. As mentioned earlier, there are a lot of things REST doesn't enforce. At times like this, it's not worth wasting too much time on it. Pick one, and stick with this design philosophy for your entire API. The key is consistency.

One of my personal tip is to read the documentation and the API contracts of popular open APIs accessible on the Internet. It gives good examples and can be source of inspiration. Here are some of my favorites:

Key-points

Using common naming conventions makes your API more predictable and easier to understand by other developers.

You don't have to start from scratch and reinvent the wheel, a lot of people came up with those battle-tested naming and structure recommendations.

REST is flexible enough to give you freedom but always plan wisely.

🔎 Always have your design proposition be reviewed by your peers

The "passionate" discussions I have mentioned earlier are not considered a bad thing in our team. Quite the opposite, we encourage challenges when designing new systems. Having various people and their own knowledge, vision and skills can help to find mistakes, typos but also fundamental design issues. These issues can be costly at a later stage of the development so you want to detect them as early as possible.

We started recently to involve not only developers in that review process but also our QA engineers.

The QA Team will be the first real client using your API. As such, it is in a formidable position to detect validation mistakes, ask more details about unclear specifications and make sure the product scenarios are covered.

"What's the exact format of that parameter representing a date? A timestamp? An ISO 8601?"

"What supposed to happen if no result is found?"

"Are we okay with an error or do we prefer an empty response?"

Everyone's opinion is valuable as long as it's communicated in a constructive way. When you give a comment, have an objection or wish to give a proposition, always explain properly your reasoning.

Key-points

More people and more point of views: Less blind spots.

It's an excellent knowledge-transfer practice of the specs of the product when performed with a constructive mindset.

📃 Document your API

I know a lot of developers don't like writing it and find it boring. But if there is something you should not skip when building a Web API, it's the DOCUMENTATION. Again, the main purpose of an API is to be used. You don't want your clients to spend hours or days trying to figure out your endpoints location, the format of the parameters or the required headers.

The minimum should be the list of all endpoints with their:

HTTP methods
List of headers/path/query parameters with their validation
The format of the body
Response and error codes and response payloads schemas.

You can write your documentation with the OpenAPI specifications (formerly known as the Swagger Specification). It quite popular and there is an entire ecosystem of tools built on top of them. But as long as your documentation is accessible and you give enough information for your API to be used, it's the most important.

It's also easier to write the documentation as you design and review your API contract. It will serve as a proper reference for the implementation and the testing.

I suggest you to look at the documentation of the following APIs. You will notice that they go further than a simple endpoints list. They also describe the global concepts and the entities they are using and also have interactive parts:

Key-points

An API without documentation is almost useless.

The documentation serves as a reference for the different team members and roles. This can help avoid misunderstandings.

Having a documentation early will be useful on ALL the following steps of the development cycle.

⏩ Next part

Now that we have designed our API, it's time to write some code and make it real.

Part 2: Implementation Phase