
Ask HN: In 2018, What makes a good API? - tpurves
What design considerations or constraints do you consider more important than others these days when designing new api services?
======
matty_makes
Documentation.

There are "standards" about REST and other mental frameworks about API's but
when it comes down to it, everything is slightly different since there are so
many small decisions that affect the end product like pagination and
authorization.

Documentation with working examples someone can use via curl or Postman (or
other API poking tool) is even better.

Tech stack doesn't matter, REST, GraphQL, micro services, etc. doesn't matter.
People are calling an API to get some work done, they just want to know how to
work with it - inputs, what happens and outputs.

------
hakfoo
Does it provide data that fits likely consumption needs?

I've seen some APIs which screan "we just mapped the database tables to API
calls". This theoretically offers loads of flexibility, but at a cost of
performance and ease in the typical case.

Think of the difference between GET /orderdetails/12345

and

GET /order/1234 GET /customer/2345 GET /product/234 GET /product/345 GET
/address/5678 GET /paymentinfo/3456 ...

------
rl3
Excellent documentation, stability, and a deprecation date of at least 2020 or
better.

------
bjourne
180 seconds (3 minutes) elevator pitch. If the authors can't provide that with
EXAMPLES then I'm not interested. Keras does it wonderfully well:
[https://keras.io/](https://keras.io/)

------
buboard
one that doesnt deprecate itself every few months for no added benefit

------
softwarefounder
Pragmatism and consistency over ideology.

