OrderDTO Customer::GetOrder(int customerID, int orderID)
GET /customer/33245/order/8769
> If we put the function name between the parameters themselves, then it leads to the question, what part of this URL is the endpoint?
But the thing that is between the parameters is "order" not the function name "GetOrder". If you look at an alternative form in which one might (more idiomatically, in some languages) see the API call, the relation to the HTTP call is more clear:
Customers[customer_id].Orders[order_id] # => Order
Yes.
They go on to say:
> A simpler API, similar to our original function call would have no mixing of parameters with the name, and clear definitions of the parameters being passed in.
With this example:
GET /customer/getOrder?customerID=33245&orderID=8769
> Why not simplify by removing parameters from the URL altogether? Put them in the query string, or post body as JSON.
Sure, RPC-over-POST is an alternative (older than REST) style of Web API, and if that's what floats your boat, do it. OTOH, "removing information from the URL for aesthetic reasons" may not be the best reason to move a safe operation from GET, which is defined as safe, to POST, which is neither safe nor idempotent, particularly if you are using middleware that is aware of HTTP semantics -- you've just thrown away valuable information.
> Your API can encounter many application specific exceptions while processing a request, but why try to pigeon hole your error response into a limited number of error codes designed for retrieving hypertext?
Why not choose the best error code of those available in the protocol? In a traditional programming language, would you just throw the most generic possible exception? Because that's what the "just use 200 for success and 500 for failure" approach is equivalent to.
> Verb agnostic, HTTP verbs are really only needed to identify where parameters will go – for GET it’s in the query string, For POST, in the body.
If you are going to use HTTP, why fight against it by throwing out its defined semantics? Aside from reducing the value you get from existing HTTP-semantics-aware software, you are just forcing yourself to reinvent the wheel.
> REST is a style, not a standard.
Whether REST is a style or a standard is irrelevant when your post is advocating abandoning it completely in favor of RPC-over-HTTP with deliberate disregard for HTTP's defined semantics.
It surprises me that the author didn't go one step further and ask us to return to SOAP :)
Yes it is relevant.People right on HN spend their time arguing over what is restful and what isn't ,because vague "semantics". with RPC,no argument.And to be frank, if you're not using HATEOAS , there is very little difference between a api with beautiful urls and a few headers and rpc.
The original spec is brilliant yet way to vague to be useful. RPC isn't HTTP,which is totally handy in the context of micro-services as one can implement RPC over any protocol. that's not the case for Rest...
The defined semantics of HTTP/1.1 methods (REST is a style, but HTTP/1.1 is a standard) are not vague.
> And to be frank, if you're not using HATEOAS , there is very little difference between a api with beautiful urls and a few headers and rpc.
If you aren't using HATEOAS, you aren't using REST. That doesn't necessarily mean that it is indistinguishable from RPC.
> The original spec is brilliant yet way to vague to be useful.
What original spec are you talking about?
> RPC isn't HTTP,
Neither is REST, though HTTP is itself an example of REST and a protocol which is fairly convenient for use in REST services.
> which is totally handy in the context of micro-services as one can implement RPC over any protocol. that's not the case for Rest...
> On the contrary, it is rather central to the point of the REST architectural style that you can implement it over any protocol (or, given hypertext formats which support identification of different protocols, over any combination of protocols simultaneously.)
From the creator of REST [0]:
A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that identification. [Failure here implies that identification is not separated from interaction.]
[0] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
So a part of the point of and value of GET is to communicate idempotency? We can know certain parts of the API are idempotent because they are GET?
But, yes, a key thing communicated by HTTP method used in a call is whether the call can be relied on to be safe, idempotent, or neither.
More importantly, your enterprise Load Balancer with timeout and failover configured will feel free to repeat a GET request internally to a different server when the first server takes too long to respond. For a POST, it will instead throw an error to a user and perhaps trigger internal alert.
And if you think that's not a big deal, wait until your bank does a double international money transfer because their trigger call was implemented accidentally as a GET request and the network latency was bad. And hope, just hope, that they are not running 10 different servers behind the firewall and therefore falling over 10-1 times.... (true horror story from my tech support days).
GET /getOrder?customerID=33245&orderID=8769
I mean, if you're going to go with this style, might as well go all-in on it, right?
GET /index.php?do=getOrder&customerID=33245&orderID=8769
If you ignore HTTP verbs and status codes you're just making it harder for other developers to grok your system. It's less about adherence to some strict standard and more about helpful signaling. A GET fetches data, POST creates new records, PUT is idempotent, DELETE deletes. 4xx status codes indicate a request error, 5xx indicate a server error. That's all useful information for someone trying to integrate with your API, but you think that instead everyone should memorize your in-house conventions. Good luck getting buy-in on that.
The only partial agreement I'd give to this is that I no longer think it's wise to nest multiple levels of resource IDs (e.g. /customer/123/order/456). This is, again, out of respect for external developers. Instead, I would have /customers/123 and /orders/456 (assuming that IDs can't be duplicated between customers). A flatter URL structure (which is, note, still REST-friendly) can be an easier-to-consume experience for other devs.
The article is basically saying "You know how lots of cars have steering wheels and pedals? Well, I think it's annoying to build cars that way, so I'm going to use a system of levers and buttons." There's a ton of utility in anchoring new systems to familiar concepts, and unless you have a good reason not to you should strive to do so.
In a fully RESTful, an external developer would be able to consume it with only documentation of the resource types used, and identification of a single base URI for a known resource from which the rest of the API's locations were discoverable. (That doesn't mean that an API owner wouldn't still want to document more, but it wouldn't be strictly necessary.)
Given the constraints developers often find themselves under, having an API that uses common patterns most developers already understand has great value. (Ex. 'GET /customer/123' performs a safe retrieval of a representation of the customer with ID 123, no documentation required)
This leaves both developers (API creator & API consumer) free to focus on documenting/understanding the non-trivial parts of the API rather than reinventing the wheel.
That's not what the article suggests (ignoring?). I totally disagree with maintaining (http verb) semantics for operations that can (and usually do) change over time. Simple JSON posts for everything make APIs simpler. There's nothing about convention, just APIs which may have irrelevant conventions.
They don't care what the internal function names are but they do care about the language of the domain, and if the internal program is well written then those will be one and the same. The HTTP verb model is inadequate for domains of realistic complexity; imagine a developer looking for the method that flubbleizes the worzwort. Is this POST /worzworts/12345 ? PATCH /worzworts/12345 ? If you squint at it then flubbleizing is kind of like adding another bishwiggle, so maybe it's PUT /worzworts/12345/bishwiggles ? Most people tend to realize that these domain-specific operations don't have a HTTP representation and instead make them a POST with the specific operation in the URL. But then you end up with an api that looks like:
#flubbleize a worzwort
POST /worzworts/12345/flubbleize
#mrefgle a worzwort
POST /worzworts/12345/mrefgle
#chezzle a worzwort
POST /worzworts/12345/chezzle
#delete a worzwort
DELETE /worzworts/12345
> If you ignore HTTP verbs and status codes you're just making it harder for other developers to grok your system. It's less about adherence to some strict standard and more about helpful signaling. A GET fetches data, POST creates new records, PUT is idempotent, DELETE deletes. 4xx status codes indicate a request error, 5xx indicate a server error. That's all useful information for someone trying to integrate with your API, but you think that instead everyone should memorize your in-house conventions. Good luck getting buy-in on that.
The developer doesn't start by knowing that something is a PUT and trying to figure out what it's doing - they start by knowing what they want to do and trying to figure out the call. The world isn't consistent enough for them to be able to guess, and splitting the call into two parts - verb and path - makes it harder to remember once you've looked it up, not easier.
4xx vs 5xx is maybe valuable, but the very fact that you xx it suggests that the difference between 412 and 422 probably isn't important. In practice every REST API I've seen has felt the need to include a response body that a) explains the error and b) includes their own API-specific error code. In which case, why repeat yourself badly in the HTTP status code?
I'm not sure of a domain where an operation cannot be represented as one of:
* Return $data
* Return a manipulation of $data that is the same type as $data
* Return a value derived from $data
* Update $data with a new value
* Create a new identifier with values that conform to the same type as $data
* Delete $data from the system
Certainly there are things like transcoding a streaming video which don't seem to map immediately, but they could if you shoehorned them. You're probably better off using something like UDP for that, though, instead of an HTTP request over TCP/IP.
Let's take images. Translation factor:
worzworts -> image (identity)
flubbleize -> encode to jpeg (non destructive manipulation)
mrefgle -> encode to png (non destructive manipulation)
chezzle -> execute image as a Piet program and return the output (derived value that is not necessarily of the same type)
POST /image/ <http://imgur.com/8XA9Eva> => 1
GET /image/1 -> identical response (except some http headers) to the imgur URL
GET /image/1/piet -> "Piet"
GET /image/1/jpeg -> /image/1 re-encoded as a jpeg
POST /image/1/jpeg -> re-encodes the gif as a jpeg and saves it to /image/1; does not conform to REST best practices because POST is for creating new records -- immediately the developer is confused
GET /image/1/piet -> <unknown, I do not have a Piet runtime> because jpeg encoding is lossy, it fundamentally changes the data source at /image/1 with an arbitrary filter; in this case, JPEG compression.
GET /image/1/jpeg -> returns a jpeg encoding of /image/1
POST /image/ <response from /image/1/jpeg> -> 200 OK, { id: 2 }
POST /image/ "Piet" -> Error 415 (images expect an image, not a string)
GET /image/2 -> returns jpeg encoding of /image/1
GET /image/1/piet -> "Piet"
PUT /image/2 <response from /image/1/png> -> 200 OK
GET /image/2/piet -> "Piet" (since png is a lossless encoding, Piet will perform the same on it)
Things go a little sideways, but not much, if these operations need parameters. But that's why they're query parameters and not a part of the url. I don't think anyone would suggest that you create a URL like
/image/1/jpeg/width/640/height/480
/image/1/jpeg/resize/640x480
/image/1/resize/640x480/jpeg
/image/1.jpeg, /image/1.png, /image/1.piet
/image/1.jpeg (image), /image/1.png (image), /image/1/piet (string)
/image/1.jpeg?w=640&h=480
/image/1.png?w=640&h=480
/image/1/piet?w=640&480 -> 400, bad request.
Or do you have some other domain in mind that doesn't involve flubber?
So optimize for that. Make it easy for a developer to look at your API with a web browser. This means simple URLs. It may mean a limited form of HATEOAS, in terms of providing links to the next things.
But it absolutely doesn't mean using HTTP status codes to convey important information. It doesn't mean using content negotiation for API versioning. It doesn't mean adopting every new HTTP verb, and frankly there's a lot of value in making every endpoint accessible over GET and POST. Those who insist on strict REST are missing why it succeeded.
How?
> worse for ease of use
How?
> worse for practically every criterion you could think about.
I can think of lots of criteria, but very few on which I can see a compelling argument for REST being inferior to SOAP except "degree of support from libraries written to support SOAP".
HTTP is a -- the prototypical -- RESTful system, and its not exactly uncommon for accessing static files on the web.
REST isn't just special-purpose APIs built on top of HTTP (nor, for that matter, does it require that an API be built on top of HTTP at all.)
However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes? Or entities in an indeterminate state? How do you aggregate multiple resources into individual request/responses for performance? How do you de-duplicate identical entities within an aggregated response? How do you return only particular fields? How do you handle paging and filtering? How do you handle transactions? How do you handle authentication and security restrictions?
All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.
In my opinion REST is fat more easier to understand for non-CRUD resources. The whole idea of CRUD makes REST sometimes seem like an HTTP adapter to the database.
However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes?
You POST the work to be done to a resource. That resource returns a URL where you can follow the state of the long running process. An alternative would be to provide a Webhook that will be called when the long running process has finished.
Or entities in an indeterminate state?
Same principle, return its actual state on a GET request (polling). Or use a Webhook (push).
How do you aggregate multiple resources into individual request/responses for performance?
Use HAL embedding or multipart.
How do you de-duplicate identical entities within an aggregated response?
Use the hypertext caching pattern in your caching layer or proxy. Use the URL as a unique key.
How do you return only particular fields?
Use HAL embedding, query parameters or a subresource.
How do you handle paging and filtering?
Use link relations and query parameters.
How do you handle transactions?
That's exactly what POST is for.
How do you handle authentication and security restrictions?
Provide a token header over https. Avoid magic URLs based on cookie state (i.e. even when you are logged in as mike your account details still are at https://example.org/user/mike/account). Restrictions are a product of the token and the requested URL.
All of these things can be solved, but by the time you've finished, your API will be far from easy to understand.
That is true, it won't be easy to understand, but it will be simple, composable, discoverabe and scalable.
It will need a load of accompanying documentation to make it usable
In my experience the opposite is true, true REST (which includes hypermedia controls) need less accompanying documentation. It makes resources more predictable and less dependendent on URLs.
All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.
In stead of making a separate resource for every action it would suffice to make one that receives actions by POSTing to it. You can respond with a URL that represents its progress. And it will also save a lot of unnecessary links or hardcoded URLs.
There is no such thing as a non-CRUD operation in a well-modeled domain. Actions in the domain are entities in the model and, therefore, are subjects of CRUD operations (often just Create and Read, but Update and Delete can also be sensible.)
> How do you deal with long running processes?
As entities that can be Created and Read.
> Or entities in an indeterminate state?
By returning a representation of the applicable wavefunction.
> How do you aggregate multiple resources into individual request/responses for performance?
By defining resources that are aggregates of other resources, and including, among the available representations for such resources, representations that include the subelements directly rather than only by reference.
This is analogous, in the RelationalDBs, to defining views (or set-valued functions, depending on the type of aggregation you are doing.)
> How do you de-duplicate identical entities within an aggregated response?
Whether or how you do this depends on the representation chosen.
> How do you return only particular fields?
By returning a representation that includes only the projection of the base resource that is of interest. I suspect the question you mean to ask, however, is how you specify a request for such a projection in REST over HTTP (REST is not tied to a particular protocol, but HTTP is the most popular one used with the architecture, and does have some particular issues in this particular case), and there are a couple of obvious alternatives:
1) Treat this as a request to create a subordinate resource to the base resource, and do it via POST, or 2) Recognize that this (like the use case met now by PATCH) is a gap in the existing HTTP method set that requires a workaround, and add a HTTP extension method (preferably, one proposed as an RFC with general semantics), such as something similar to WebDAV's REPORT or SEARCH (but not so application-specific.) REST doesn't -- with an extensible protocol like HTTP -- mean you have to be limited by the base protocol, it just means you have to be judicious in your use of extensions. [0]
> How do you handle paging and filtering?
Same answer as the previous question (in fact, paging and filtering are essentially the same thing as the previous question.)
> How do you handle transactions?
A unit of work that is logically linked in the domain is an entity in the domain that can be Created, Read, Updated, and Deleted (particularly C = BEGIN , U = COMMIT, D = ROLLBACK.) Actions within the transaction can either reference the transaction in resource representations or be subordinate resources to the transaction itself, depending on context.
> How do you handle authentication and security restrictions?
Generally, Authentication is communications-protocol dependent and how security restrictions are enforced is outside of the scope of REST.
[0] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... : "A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field."
Caching. Put a caching proxy in front of your api endpoint and enjoy.
This is the same reason you'll want to do:
/api/customer/1234/order/abcd
/api?customer=1234&order=abcd
urllib.urlencode(sorted(params.items()))As far as REST vs. RPC goes, there is a sole essential difference: the semantics of interaction with a REST resource are defined in RFC 2616, and a correctly designed and implemented REST resource behaves in accord with what you find there.
REST itself, meanwhile, being just HTTP, is very simple, and very well suited to expressing interactions with resources and collections of resources. Especially in the front-end/full-stack development world, most things can be expressed, with little or no semantic strain, as resources and collections of resources, and capable HTTP clients are highly available. (And the convention of encoding structured data as JSON in request bodies is very strong, besides.)
Conversely, there are as many RPC-over-HTTP standards as there are implementations; since doing RPC over HTTP necessarily means mapping whatever semantics you have in hand to an interface not designed to express them well, this makes headaches for people who have to develop against them, especially when writing an application that draws together many disparate APIs in order to do something interesting at their conjunction.
Whether REST is better than RPC over HTTP, or vice versa, strikes me as a question for a philosopher. But, in most cases of interacting with a remote resource over an HTTP transport, REST is certainly more natural, that is, closer to the native semantics of the transport, which results in thinner glue layers and more easily understood behavior.
REST as an architectural style wants you to think as your API as a collection of resource representations that can be manipulated through simple verbs (as the one present in HTTP).
It forces you to think about idem-potency, caching, namespacing, immutability and robustness.
If your API doesn't have abstractions for long running processes or more complex business transactions, you don't have a RESTful API and need to adapt it.
Furthermore, if payload size and minimizing the number of requests is your most important goal, why are you using HTTP in the first place? It's not the right solution for you.
And the idea that using HTTP somehow renders questions of performance irrelevant is bizarre. If Hacker News sent 10MB of uncachable CSS, spread over 100 HTTP requests, with every page load, would that be OK because performance isn't the most important goal of the web? People use HTTP because it's a ubiquitous protocol supported by virtually every device and language. Performance isn't the most important goal, but it's still an important one.
[1] http://steve-yegge.blogspot.co.uk/2006/03/execution-in-kingd...
I'm wondering why Thrift/Proto-buffers aren't popular? Even for browser-based JS clients. What're the pitfalls?
Following the REST patterns means you can take advantage of things like standard agnostic intermediaries for caching & filtering. You can switch or even spread across service providers by changing domain names in URLs. You can mitigate network issues through guaranteed idempotence and using conditional headers like if-none-match. These are all issues that you'll probably have to rediscover and re-solve on your own, if your API lives long enough.
It is not about SEO or visually "clean" URLs. REST says nothing about that, despite many misconceptions otherwise. In fact, in a truely RESTful service, resource URLs can be obscure garbage like http://example.com/A13D-DE45-32BC. If you're using the HATEOS principle, those URLs will be picked up from links in your responses.
"Pidgeonholing" your errors to standard HTTP error codes means that you've followed a shared standard, rather than inventing your own from scratch. Also, 4xx errors generally refer to something in the client's request, while 5xx errors generally mean something has gone wrong while generating a response on the server side.
If you don't need any of these things - because, say, you're building an API that will only be used between two parts of your own small system - then don't worry about REST. Go ahead and build something along RPC lines.
You might regret it someday, if you find yourself needing the scaling characteristics of the WWW. But, many systems never grow to that point anyway.
There is no such thing as a RESTful URL. Characters in URLs don’t matter.
GET and POST have different semantics. Ignoring the benefits of caching is just dumb.
The semantics of status codes and verbs are defined pretty clearly. You might have to read an actual spec.
A paragraph starting with “A core difference between REST and RESTful …” physically hurts.
I can’t believe I just wasted time actually commenting on this.
Let me introduce you to a little something called objects.
GET /index.php?do=getOrder&customerID=33245&orderID=8769
Actually, I don't really know. But for sure HTTP isn't forcing you to only use GET/POST/PUT/DELETE, even if this verbs are usually enough to design your API. It's quite funny to hear some people (I'm not talking about the author) joking about the "418 I'm a teapot" response status, which is defined in a HTTP extension, and then telling you that having only 4 methods to design an API is too restrictive.
HTTP is extensible, so why misusing it?
I also think that your customer order example could have been done better. Something like
Your example: OrderDTO Customer::GetOrder(int customerID, int orderID) But that's the wrong side of the equation, that's the definition of the function. If you call the function it would look like this: GetOrder(myCustomerID, myOrderID)
And an equivalent REST call would look like this with a little clean up. GET /orders/?id={id}&customer-id={customer-id}
Doesn't look that much different to me. Sure you could have done GET /orders/{id}/?customer-id={customer-id}, but there is no reason why the above is wrong from a RESTful perspective. Why would you marshall a whole JSON payload to do a simple GET? You are not creating a tuple to pass the two parameters in your full-language function example, what's the reason it is required for the RESTful call?
As I mentioned above HTTP needs a couple more verbs and aliases for the existing verbs. You think of situations like:
START /timers STOP /trains
A lot of the time we jam POST and PUT in this situation and they are poor substitutes for a larger verb vocabulary. I have built a few automation projects and any actions you do can usually fit into
NEW GET UPDATE (merge) DELETE START STOP OPEN CLOSE
still limited, but pretty good at covering almost all the verbs needed. You supply the nouns.
NEW /vms START /vms OPEN /remote-desktop/1234 CLOSE /files/folder/path/to/file
Especially with persistent connections in HTTP2 and web sockets and things of the kind OPEN and CLOSE will likely be need to establish these kinds of connections. You could probably get away with using START and STOP though, such as:
START /remote-desktop/?computer=1234
As for HTTP error codes. They need an overhaul. 404 and 403 do the job fine, but giving the user an idea of whether their JSON was malformed (Syntax) vs. the data in the payload was invalid is difficult to distinguish with just 400. But the return payload should describe the error in detail. Not many conventions there to help.
As for HATEOS, I used to think it was great, but I am meh on it now. It needs refinement.