Vinay Sahni

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-that-creates-something/

[SHAREDOM-HN] https://news.ycombinator.com/item?id=8160071

[FOWLER] http://martinfowler.com/articles/distributed-objects-microservices.html

[FOWLER-HN] https://news.ycombinator.com/item?id=8172980

[LEGO] http://nordicapis.com/legos-api-strategy-resourcing-developers-building-business-case/

[ORLIESAURUS] https://medium.com/@orliesaurus/a-review-of-all-most-common-api-editors-6a720dc4f4e6

[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]…

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

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-duplicate-http-get-query-keys

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#autoloading

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.

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

Here are a couple more lists of Best Practices for REST APIs.

http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

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/