3 ms·

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 Leon

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/ 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 solid examples that you build upon throughout each chapter, and jumping off points to standardisation work like JSON-LD etc.

fzilla 10y ago
this this this this this this I cannot recommend this book enough. Read it, read it again, take in everything it is trying to say and try as hard as you can to understand it. There is a whole world of awesome and tragically misunderstood tools in the book.
MichaelGG 10y ago
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 adding needless details, or requiring me to set a bunch of options on my HTTP request. Hint: setting a bunch of headers and a verb is not easier than passing some querystring params.
- fzilla 10y ago
  The HTTP spec exists to help you interact with resources in a specific way. 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/<id>/publish or PATCH /entries/<id> 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.

fzilla 10y ago

this this this this this this I cannot recommend this book enough. Read it, read it again, take in everything it is trying to say and try as hard as you can to understand it. There is a whole world of awesome and tragically misunderstood tools in the book.

MichaelGG 10y ago

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 adding needless details, or requiring me to set a bunch of options on my HTTP request. Hint: setting a bunch of headers and a verb is not easier than passing some querystring params.

fzilla 10y ago
The HTTP spec exists to help you interact with resources in a specific way. 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/<id>/publish or PATCH /entries/<id> 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.