DEV Community

Cover image for What makes a great API?
Nick Taylor
Nick Taylor

Posted on

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!

Top comments (9)

Collapse
 
zisra profile image
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)
Collapse
 
thomasbnt profile image
Thomas Bnt

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

Collapse
 
ashishk1331 profile image
Ashish Khare😎

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

Collapse
 
giovannimazzuoccolo profile image
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...
Collapse
 
stefjoosten profile image
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.

Collapse
 
respect17 profile image
Kudzai Murimi

Thanks a lot!

Collapse
 
velydev profile image
Vely

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.

Collapse
 
buchslava profile image
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;)

Collapse
 
tandrieu profile image
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.