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.
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
...
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/
6 comments
[ 3.7 ms ] story [ 16.3 ms ] threadThere 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.
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 ...