81–90 of 101 posts
http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...
http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...
There is also this Medium post: https://bradfults.com/the-best-api-documentation-b9e46400379...
When doing my last bigger API i read every recommendation. Still learned a lot. Everyone has different recommendations - dont get discouraged by this. Make sure also to look into newer standards like JsonAPI if they are suitable - last time i tried to use it the tooling around it was still not strong enough and i decided to go w/ simpler custom api. Assuming it has to be a restful api (vs graphql) and assuming you wa…
Never nest data (not `post: { author: { … } }` but reference only `post: {author_id: …}`) I'm creating a huge API on my dayjob and we have nested A LOT. So many levels of nesting, the responses have become too big. Yet, the clients refuse to call additional endpoints and always insist on this. And it _does_ make sense for them to make 1 call and retrieve all information they need. How does everyone handle this on RES…
This eventually can become the basis of your test harness. In fact, every time I write my tests, I end up writing a client library...
I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break your API: http://amberonrails.com/building-stripes-api/ http://amberonrails.com/move-fast-dont-break-your-api/
The amount of versioning that Stripe does makes nervous. Is that a good practice?
In Stripe's case, I normally find an initial integration is a better experience than most payment services. The API is reasonably designed and well documented.
However, I also find Stripe integrations are effectively impossible to maintain or update over time. Older API versions aren't documented anywhere I can find, only the current one. There are decent changelogs with warnings of incompatibilities, but you can't write an automated integration test suite. I've never found any documentation that explains how their versioning actually works, what is affected, and how to revert if you update and there's a problem.
In practice, that means older versions of the API aren't fully supported indefinitely, nor is there a safe, systematic path to manage an upgrade to a newer API version. For that reason, we normally treat Stripe integrations as write-only code, where once you've got something written, tested and into production, it's never touched again (short of a serious security issue or the like, obviously).
I always liked Rusty's list on making an API "hard to misuse" (and its followup): https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html
This page is a more concise overview of the levels: http://sweng.the-davies.net/Home/rustys-api-design-manifesto
>The number of APIs produced by Google’s various business units grew at an astounding rate over the last decade, the result of which was a user experience containing wild inconsistencies and usability problems. There was no single issue that dominated the usability problems; rather, users suffered a death from a thousand papercuts. A lightweight, scalable, distributed design review process was put into place that has improved our APIs and the efficacy of our many API designers. Challenges remain, but the API design reviews at scale program has started successfully.
http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvea...
I think it depends on what type of API you'd like to design. If you're talking about REST APIs, then the best book I've come across is RESTful Web APIs by Leonard Richardson and Mike Amundsen: http://restfulwebapis.org/ It actually shows you how to do REST properly, not that shoddy knock-off REST that some people push, where you have to document all your URI structures and hard-code them in your clients. There's soli…
Why should anyone care about doing "REST properly"? I've never seen a convincing argument. I've used REST and "shoddy REST" and haven't seen much indicators in quality one way or another. In fact, far beyond the actual design is the question if they provide client code. That makes so much more of an impact. Indeed the only real negative I've seen is people going out of their way to make it REST and in the process add…
In my experience, the "shoddy REST" the original commenter is talking about usually involves developers ignoring the design principles behind HTTP and trying to pretend like they can't or don't need to map their organization's domain model to HTTP's resource model. This typically happens because they either don't understand how to do this, don't have time, or think that the effort involved to rethink their model isn't worth the effort.
What they end up with is a cobbled-together mess of endpoints that perform unintuitively specific functions constructed in the language of a system that wasn't designed to work that way.
A really good example of this might be a blog API. Which is better?
POST /entries//publish
or
PATCH /entries/ with a request body of { published: true }
The POST seems more immediately intuitive to the API developers, because they can just add all publish-related tasks in the publish route handler or controller and call it a day. But the PATCH is more immediately intuitive to the API consumer, because they probably understand that entries have a "published" field (this gets more into hypermedia and semantics and beyond the scope of this post), and that PATCH allows them to change a field, and that if "published" is true then the entry is live.
A good analogy is trying to construct your own special-purpose language using English words, but with totally new meanings and purposes for each word, then expecting to communicate with others in this language. It superficially looks like English, but cannot be understood without volumes of documentation explaining how it is different.
When doing my last bigger API i read every recommendation. Still learned a lot. Everyone has different recommendations - dont get discouraged by this. Make sure also to look into newer standards like JsonAPI if they are suitable - last time i tried to use it the tooling around it was still not strong enough and i decided to go w/ simpler custom api. Assuming it has to be a restful api (vs graphql) and assuming you wa…
Never nest data (not `post: { author: { … } }` but reference only `post: {author_id: …}`) I'm creating a huge API on my dayjob and we have nested A LOT. So many levels of nesting, the responses have become too big. Yet, the clients refuse to call additional endpoints and always insist on this. And it _does_ make sense for them to make 1 call and retrieve all information they need. How does everyone handle this on RES…
{
posts: [ /* 100 records */ ],
authors: [ /* 3 records */ ]
}
http://apigee.com/about/resources/ebooks/web-api-design
I was impressed with the Rackspace Cloud API and documentation too. Especially their authentication services.