Before leaving my current place, our Architect built a PHP micro-framework for our APIs that follows 90% of what's outlined here. I never really understood the magnitude of his work until I tried developing a new API in a different framework. Intelligent routing and query param handling all baked in is so rad.
Designing a Pragmatic RESTful API
111–120 of 139 posts
Re: Designing a Pragmatic RESTful API
#112Earlier quoted context omitted.
There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation. Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty application…
This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place? Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.
You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
Re: Designing a Pragmatic RESTful API
#113Earlier quoted context omitted.
Sure, but peterwwillis was likely making the point that REST sometimes just gets in the way. REST itself is not complicated, but trying to make it work where it shouldn't can complicate what you're trying to do. Not all APIs can be modeled well with the "resource" or "document" concept. A lot of times all you really want is to ping an endpoint and get/post some data.
Maybe HTTP is simply missing the INVOKE verb for executable documents.
That's already POST, basically.
Furthermore, if you really wanted to, HTTP does allow new verbs to be added, so...
Re: Designing a Pragmatic RESTful API
#114Great article. I'm actually in the middle of building out a new API. I've built many RESTful APIs but I'm starting to rethink of a couple of things with this new one. Does anyone have any good resources on when it's NOT appropriate to use REST? Or is the assumption that it should generally work for anything if you model it right? I ask this because the API I'm building is for a B2B product and lot of the "actions" ar…
> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don'…
> It should generally work for anything if you model it right.
No, this is not true. Each constraint of REST comes with drawbacks, and if you can't afford those drawbacks, you can't do it RESTfully. Fielding's thesis is very upfront about this.
The biggie: latency. If you need sub-10ms responses, REST is the wrong way to go about modelling your problem domain.
The second: client-server. If you want the server to initiate behavior on the client, REST is the wrong way to go. See the wealth of WebSockets/Meteor/Real Time Web (tm) frameworks and their hype for examples of when you'd want to do this.
Re: Designing a Pragmatic RESTful API
#115We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article. The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. I've built a couple of very pure R…
The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs http://…
The blog you linked seems to miss the point. (Which I think is what you're saying.)
If people try to guess URLs for what you see as (for example) steps 3-7 of a ten-step process, maybe you should see what your users are trying to tell you - that it's at least three smaller tasks that need to be usable individually.
And if there really is some reason to force them to use your workflow (perhaps you want to push ads in step 2 and not release content until your javascript sends home a message saying the ad is visible) then you need to do it right and give them an unforgeable token, or make note of an existing unforgeable token - ie what a cookie is for.
This is what the obfuscated URLs are (something unforgeable) but this fact of their nature mainly makes debugging harder - for third-party developers and for the primary developers.
This is an example of the problem of the non-experts re-inventing security. At best this matches existing common practices for user-auth, at likely worst it's worthless and you'll never know it because you can't debug it.
So yeah, I think I agree. Hashing URLs for some sense of control over how they're used misses the boat on security and wastes all the benefit of human-readable protocols, etc.
Re: Designing a Pragmatic RESTful API
#116Earlier quoted context omitted.
This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place? Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.
You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
But who has truly RESTful objectives in mind? Are there any widely used REST APIs that truly adhere? I acknowledge that there may be. It's just the ones I come across always make significant concessions. Sometimes people tell me that "the web as a whole" or RSS are examples, but those seem too fundamentally different from any API I might create.
Re: Designing a Pragmatic RESTful API
#117Earlier quoted context omitted.
You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
But who has truly RESTful objectives in mind? Are there any widely used REST APIs that truly adhere? I acknowledge that there may be. It's just the ones I come across always make significant concessions. Sometimes people tell me that "the web as a whole" or RSS are examples, but those seem too fundamentally different from any API I might create.
The GitHub API is pretty damn close these days, and I can tell you that there's a very big company you've heard of with a two-digit person team working on a HAL-based hypermedia API right now. Twilio has been pretty good too.
There are lots of private APIs that operate this way; for example, much of Comcast's internal stuff is pure, hypermedia driven REST. But it's not open source, so you don't hear about it.
A YC-funded company, Balanced Payments, does an excellent job as well.
> those seem too fundamentally different from any API I might create.
Right! That's because you're primarily thinking of RPC styles, so of course it will seem foreign. Try this sentence on for size, from a different time period:
"But who has truly object oriented objectives in mind? Some people tell me that Smalltalk or C++ are examples, but those seem too fundamentally different from any code I might write."
That's not to say RPC is a bad thing: often times, it's just fine. But if you have the problems REST is designed to solve, REST will solve them much better.
Re: Designing a Pragmatic RESTful API
#118We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article. The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. I've built a couple of very pure R…
The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs http://…
The other benefit of defining the endpoint in the resource is that you can send the request somewhere else. Sharding your API, so to speak.
Re: Designing a Pragmatic RESTful API
#119Earlier quoted context omitted.
Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.
>Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Why, no, it doesn't, because it takes 3 parameters, each of which can take 10,000 possible values, and I don't want to transmit a trillion options every time someone pings the root. I mean, I considered documenting how to pass the parameters on a client's first entry but the HATEOAS crowd told me…
[deleted]
Re: Designing a Pragmatic RESTful API
#120Earlier quoted context omitted.
Once people stop calling it the wrong thing, the discussion can be about something else. I also hate this nitpicking, but it's clearly not going away so you're better off not inviting it by using the term incorrectly.
It's why I've come to prefer the term "RESTish". It probably still isn't enough to mollify hard-core purists but indicates that, e.g. the user knows versioning ought to be in the accept header rather than the URL, but also that hardly anyone either creating or using web APIs cares.
[deleted]