What makes a great API?

Proper JSON types, for instance:

• Numbers are numbers, not strings.
• Dates are represented as numbers
• Uses objects to represent linked values (coordinates.x and coordinates.y instead of xCoordinate and yCoordinate)

A great documentation, good routes and makes that simple to access data's.
Easy to remove datas about GDPR.

I like to joke with my backend colleagues: 'A great API makes the frontend stupid.'

For example:

• Great documentation
• Self explainable endpoints
• Pagination and querying consistent
• Error handling and error documentation
• Works well with tools as Postman, Hoppscotch...

What I need most is to trust an API to do precisely what it is supposed to do; no more and no less. For that, I need for every API-call:

1. Unambiguous preconditions, to prevent erratic behaviour and security loopholes. If a precondition is not satisfied, the API responds with an appropriate error.
2. Unambiguous invariants, to safeguard the semantic integrity of data. The API promises to keep all of its invariants satisfied at all times.
3. Unambiguous postconditions, so I know exactly what the output will be.
4. The API does nothing beyond what is specified in the previous three requirements.

There are other desirable features, but these four trump all others.

Thanks a lot!

As close as possible to 1:1 mapping to business rules. Not always possible, but I've seen APIs that try to be too generic (possibly anticipating every possible future business requirement), and end up being too complex and unusable.

1. Clean endpoints structure. I'd say, even self documented. Every team member familiar with the project specific should generally underderstand what the endpoint does according the endpoint without additional doc.
2. Proper request methods usage.
3. Ability to test the API interactivity. For example, I'm fond of Apollo GraphQL solution approach regarding testing and documenting.
4. Proper technological choice. Depends on business requirements. NodeJS, Golang, Rust...
5. Error handling including log system and the ability to stop/restart the API in case of crash/stuck (if we consider non-cloud solution). Moreover, Devops support - based artifacts...
6. Performance monitoring.

That's it for now. Maybe will remember other cases if lucky;)

I just wrote an article on How to design good API. Not only REST API, but any kind of API:

kissyagni.wordpress.com/2023/07/28...

I would summarize it by:

Not because you did something complicated means you did something smart.

API is the UX of your service. Whatever the complexity of what you are doing, API should be easy and intuitive for end user. And writing documentation is not an excuse for badly designed API.