Vinay Sahni

https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api Helped me get started with API design in my early career. Learning from other existing APIs helps too. such as stripe, github, shopify. Any others? Something that We do at my current job: * set a standard and stick with it. tweak it if needed. we even have naming standard on some of the json key. for example, use XXX_count for counting. when it doesn't make sense, use total_XXX. * Document your API, we use postman and code review API changes too.

Use REST for reading, but RPC-style calls for writing. Benefits: 1. Every write-call is a transaction 2. You can have complex filtering and sorting in the read/access side of your API without having to worrying about the update-side of things. 3. You can evolve the read-API, even change semantics and return different objects and again, not worry about transactions. 4. You are not limited to the HTTP-standard. Here are also some good tips: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Not on a technical slant, but here is a good, pragmatic API design guide by Vinay Sahni that I came across a couple of years back [0]. It gave me a ton of good ideas on how to design the API for our SaaS app. [0] - http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

1) Does all this depend on use case? Yes, heavily. Best practices are needed, but final design choices are tailored. 2) I don't like dup query params, it's not well defined: http://stackoverflow.com/questions/1746507/authoritative-position-of-d… For returning multiple types at once there are a few common strategies. For related types some APIs offer an "include" or "embed" approach like this: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#a… Another approach is to support a query syntax for items, where items is a container record for multiple possible types. If a certain multi-type scenario super common you may want build the concept into the API itself as basic functionality. Again, your final choice should be as simple as possible but no simpler, taking into account ease of use, performance, etc.

There should be only one API design guideline. http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api.

Here are a couple more lists of Best Practices for REST APIs. http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-… http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api The Github team does a pretty good job of incorporating modern best practices as well, so I often use their API as a reference: https://developer.github.com/v3/

This is a much (much :-)) better post about "REST"/"HTTP" API best practices: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

I agree with most of Vinay Sahni's points: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

A slog indeed. For anyone interested, this is the article I hand out when someone asks me about designing a REST API: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api?h… And here is the HN discussion from when it was originally posted: https://news.ycombinator.com/item?id=5819231

I use the following sources as standards: - Vinay Sahni's Best Practices for Designing a Pragmatic RESTful API: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api - HN discussion on Vinay's post: https://news.ycombinator.com/item?id=5819231 - Twitter's Error Codes & Responses: https://dev.twitter.com/docs/error-codes-responses

[url]http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api[/…

> authorization Hmm. Is authorization maybe very app specific? Did you mean authentication?: Basic Authentication and API keys and HTTPS seems popular. E.g. Stripe: https://stripe.com/docs/connect/authentication#api-keys, and Chargebee (they deal with tons of money). I like this article: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api — except that I use only POST and GET, never PUT, DELETE etc. And name the endpoints like: POST /-/create-page controllers.PageController.createPage POST /-/pin-page controllers.PageController.pinPage POST /-/unpin-page controllers.PageController.unpinPage POST /-/reply controllers.ReplyController.handleReply GET /-/load-draft-and-guidelines controllers.EditController.loadDraftAndGuidelines GET /-/load-draft-and-text controllers.EditController.loadDraftAndText POST /-/edit controllers.EditController.edit then one knows what and endpoint does, by just looking at the URL path. Won't also need to ask: "But which method?" Also, most people that actually design APIs, seem to put the API version in the URL, like `/api/v1/...`.

You may find some of these helpful: • Web API Design Crafting Interfaces that Developers Love - eBook [APIGEE] • How to design an API function that creates something [SHAREDOM] [SHAREDOM-HN] • Microservices and the First Law of Distributed Objects [FOWLER] [FOWLER-HN] • Lego’s API Strategy: Resourcing Developers and Building a Business Case [LEGO] • A review of all most common API editors — Medium [ORLIESAURUS] [ORLIESAURUS-HN] • Best Practices for Designing a Pragmatic RESTful API [VINAYSAHNI] [VINAYSAHNI-HN1] [VINAYSAHNI-HN2] • Best practices for API versioning? - Stack Overflow [SO] [SO-HN] • Designing Hypermedia APIs [KLABNIK] [APIGEE] https://pages.apigee.com/web-api-design-ebook.html [SHAREDOM] http://sheredom.wordpress.com/2014/08/10/how-to-design-api-function-th… [SHAREDOM-HN] https://news.ycombinator.com/item?id=8160071 [FOWLER] http://martinfowler.com/articles/distributed-objects-microservices.htm… [FOWLER-HN] https://news.ycombinator.com/item?id=8172980 [LEGO] http://nordicapis.com/legos-api-strategy-resourcing-developers-buildin… [ORLIESAURUS] https://medium.com/@orliesaurus/a-review-of-all-most-common-api-editor… [ORLIESAURUS-HN] https://news.ycombinator.com/item?id=8505244 [SO] http://stackoverflow.com/a/398564/2541 [SO-HN] https://news.ycombinator.com/item?id=7350432 [VINAYSAHNI] http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api [VINAYSAHNI-HN1]…