What makes a great API?

What are things you look for in a great API?

I’d love to hear your thoughts on various aspects like a spec, e.g. OpenAPI, where you think is a great place to host your API, resilience, handling errors, observability, testing etc.

If you have examples of great APIs even better! And if you have recommendations for tools to help with your awesome API share those as well.

I’m curious to see people’s stacks and tools!

Comments

[Stef Joosten]

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.

[Thibaut Andrieu]

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.

[Giovanni Mazzuoccolo]

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...

[Vyacheslav Chub]

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;)

[Kudzai Murimi]

Thanks a lot!

[zisra]

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)

[Thomas Bnt]

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

[Ashish Khare😎]

Yup, documentation is the key. Also, semantic routing which makes any url endpoint readable and helps to figure it out intuitively.