Designing Pragmatic RESTful APIs
info.apigee.com
Designing Pragmatic RESTful APIs
1–10 of 21 posts
Re: Designing Pragmatic RESTful APIs
#2Insert standard comment about how this does not touch on HATEOS and is therefore not only not REST, but evil and perverse and all that is wrong with the world
Re: Designing Pragmatic RESTful APIs
#3I rather like the "Richardson Maturity Model" described by Martin Fowler:
http://martinfowler.com/articles/richardsonMaturityModel.htm...
This gives different levels of "conformance" with the spirit of REST without name calling.
Re: Designing Pragmatic RESTful APIs
#4Developing REST API per definition of REST cannot be done pragmatically in the way described, so you are going to screw a lot of people if they think this is the last word on REST.
1. REST is a hypermedia API that (somewhat) describes its own services by returning URLs to resources, etc.
Most people don't understand what REST was meant to be that can drive how REST clients were meant to be developed. Some of the major players with "REST" APIs don't either.
2. REST does not have to be versioned if for internal use.
I actually agree with the versioning part, however I've also been on two teams over the past 10 years that developed versioned APIs and neither time did versioning matter, because those APIs were for internal use.
3. This is not a RESTful requirement, but, practically, you shouldn't design an API that allows any querying of resources beyond what should be needed.
This is because of the memory required for caching responses (in a large application), because it therefore can be an easy target for attacks (lets throw a bunch of query params on here... mwhahahahaha), and just because it opens up security holes. Be explicit in what is allowed in your code and your documentation.
4. The querying and filtering I see in this document is insufficient for some applications and interfaces.
It didn't take us long to run into the limitation of the search functionality described in this document in our current REST API based app.
Re: Designing Pragmatic RESTful APIs
#5This isn't bad and collects a lot of random useful advice in one place but I have a few beefs with it:
repeat akavi's standard comment about HATEOAS here it really does solve some of the problems they're trying to workaround with carefully crafted URLs and versioning. Links are discoverable even if you can't manage to make your URLs clean or even stable.
I think their bit on error codes is all wrong: Using an unfamiliar code number won't throw a human at all, as they come with a self-descriptive label like "Gone" or "Conflict", and should have a body with an explanation of what happened. (Which they recommend) Error messages are for tools, libraries, and proxies; you should use whatever code gets you correct behavior from them (even if it makes no sense), but there's no value in carefully reducing the set of codes you use.
They have some slightly confused ideas about hierarchies, like suggesting version numbers always go at the root. Surely version numbers should be at whatever level the API gets versioned? If you religiously put your versioning at the root, you're going to wind up with the standard API compatibility problem where someone wants to use a v3 feature so they (have to) upgrade all their calls to v3 and then get angry when there's some unrelated compatibility break. Good advice on making it mandatory though.
For God's sake don't allow GET with &method=delete or the like. You can narrow your verbs down to POST and GET but no further.
Insert mention of CSRF here.
The whole architecture section "The API Façade Pattern" is just a bunch of waterfall, API-first design nonsense. Don't invent an API in outer space then try to integrate it with a real system designed separately.
The whole point of decomposing your API into actions on resources is that you don't have to have one unified, consistent, holy API, each resource is an API unto itself that can live on its own and follow its own rules to get something done. If you really love consistency, go whole hog and be consistent with the whole world by using standards, being consistent with just yourself is a form of masturbation.
Re: Designing Pragmatic RESTful APIs
#6Totally agree @hakaaak, especially with the care that should be put into making the API navigable using hyperlinks.
It's kind of cool to have a browser-friendly API to play with in the beginning, but it should be pure bonus. APIs are designed to allow a computer program to interact with another one. Favouring query strings over HTTP headers for anything other than altering the projection of a resource is non-sense.
I also don't seem to understand why we must reinvent the wheel and duplicate features when HTTP clearly mentions how to specify an output format, and how to handle partial responses (Range, Content-Range, 206 Partial Response, etc).
PUT is not the equivalent of "update" in CRUD. PUT is meant to replace an existing resource projection with another one. PATCH is the way to go if you want to update specific attributes of an existing resource.
And what about ETags? conditional requests?
It kills me when people mix pragmatism with embracing years of bad practices. That's how we end up with standards where history and legacy are more important than common sense.
Re: Designing Pragmatic RESTful APIs
#7I rather like the "Richardson Maturity Model" described by Martin Fowler: http://martinfowler.com/articles/richardsonMaturityModel.htm... This gives different levels of "conformance" with the spirit of REST without name calling.
I just got round to reading that article last week, it's incredibly informative and like you say, avoids any mud slinging.
Re: Designing Pragmatic RESTful APIs
#8Developing REST API per definition of REST cannot be done pragmatically in the way described, so you are going to screw a lot of people if they think this is the last word on REST. 1. REST is a hypermedia API that (somewhat) describes its own services by returning URLs to resources, etc. Most people don't understand what REST was meant to be that can drive how REST clients were meant to be developed. Some of the majo…
Could you explain a bit more on the limitations of the search functionality and how you got around it? Would likely be very useful.
Re: Designing Pragmatic RESTful APIs
#9If I had to restart my API over again I would make it self-documentable.
Browsing to /dogs with an Accept: text/html would include a description about that end-point with the possibly accepted parameters, and links to related resources.
If authenticated it would also include the content of that actual route and maybe even a small JavaScript request builder.
Re: Designing Pragmatic RESTful APIs
#10Developing REST API per definition of REST cannot be done pragmatically in the way described, so you are going to screw a lot of people if they think this is the last word on REST. 1. REST is a hypermedia API that (somewhat) describes its own services by returning URLs to resources, etc. Most people don't understand what REST was meant to be that can drive how REST clients were meant to be developed. Some of the majo…
I agree with point three but that could be partially mitigated by throttling, could it not? I recall a good post about making a good API that developers enjoy using and query throttling was a an important point.