The Restful CookBook
21–30 of 53 posts
Re: The Restful CookBook
#22Earlier quoted context omitted.
> 404 should be reserved for URL/route errors. What dichotomy are you working off of here? It is absolutely a 404. How is this any less applicable to a DELETE request than it would be to a GET request for the same resource? What extra information would this new status status code carry? ---- > 10.4.5 404 Not Found > The server has not found anything matching the Request-URI. No indication is given of whether the cond…
Ok, so client requests "DELETE www.company.com/api/thing/1234" and gets a 404. Or even "GET www.company.com/api/thing/1234". Delete vs get doesn't matter. Did 1234 not exist, or is "/api/thing" the wrong path? 404 is overloaded. It can mean two very different things.
"is /api/thing the wrong path" - is fixed by hypermedia, so 404 generally means that resource cannot be found.
Re: The Restful CookBook
#23Earlier quoted context omitted.
> 404 should be reserved for URL/route errors. What dichotomy are you working off of here? It is absolutely a 404. How is this any less applicable to a DELETE request than it would be to a GET request for the same resource? What extra information would this new status status code carry? ---- > 10.4.5 404 Not Found > The server has not found anything matching the Request-URI. No indication is given of whether the cond…
Ok, so client requests "DELETE www.company.com/api/thing/1234" and gets a 404. Or even "GET www.company.com/api/thing/1234". Delete vs get doesn't matter. Did 1234 not exist, or is "/api/thing" the wrong path? 404 is overloaded. It can mean two very different things.
Ah, I think I understand what you're getting at now, that's a really interesting question.
I can't entirely back this up without probably days of reading RFCs, but my initial gut feeling is that making this distinction, which is not really possible in a truly general way (provided the URI is a syntactically correct HTTP URI), would be exposing internal implementation details in a way that would be conceptually inconsistent with other HTTP response statuses.
eg, how to usefully and consistently make the distinction:
GET /asfd
200 OK
GET /qwer
4XX We don't have that right now
GET /zxcv
4XX That is not even a thing
It might make sense in certain circumstances of RESTfully-modelled resource URIs layered on top of HTTP:
GET /users/asfd
200 OK
GET /users/qwer
4XX We don't have that right now
GET /blarghs/asdf
4XX That is not even a thing
----
Disclaimer: I have no idea what I'm talking about and am not entirely convinced by my own argument. I'm always skeptical of "that's just not how it's done right now"-flavoured arguments, which this doesn't stop smelling like as I attempt to reason about it.
----
As practical matter, the body of the 404 response can describe the situation within the context of the application. And if your application is smart enough (though to do this in the general case is impossible or would require something like strong AI), you can use any of several more specific responses (Gone, Found, etc; depending on the context) if you're willing and capable of inferring a specific intent from the otherwise bad request.
Re: The Restful CookBook
#24While some of the tips are useful, I'd much rather see them written with JSON rather than XML. JSON has long been an industry standard. XML is bloated, almost no one uses it anymore. http://restcookbook.com/Mediatypes/json/ says "There is no predefined way to deal with link discovery in JSON". I'm surprised it doesn't even mention JSON Schema ( http://json-schema.org/ ) or JSON API ( http://jsonapi.org/ ), which are…
"XML is bloated, almost no one uses it anymore."
XML bashing is quite common these days. But I'd like to point out that it's the use case that matters when deciding between JSON and XML. Almost all "enterprise" software prefer XML over JSON.
https://www.quora.com/Markup-Languages/What-are-the-advantag...
Re: The Restful CookBook
#25I just started at a new job, at a new startup. During the my first job interview with them, they asked, "Do you know how to work with a RESTful interface?" I said yes, and I told them to look at my Github account for examples. During my second job interview with them, they asked "What do you consider when you are designing a RESTful interface?" I quoted a bit from the book that Sam Ruby and Leonard Richardson wrote,…
> Their system is not RESTful at all IHMO ,The problem is nobody has a clue what REST or RESTful really means,at least I don't. But it's clearly not a protocol. It's not even a well defined pattern that exposes clear behaviors with rules. Some developers don't like that, they want clear goals to do their work and want canonical examples they can point to when arguing with colleagues. So personally I understand the ap…
REST is well defined, it's just that most guides don't explain it well. REST is just a list of 6 possible characteristics of network protocols/architectures (Client/Server, Stateless, Cache, etc), and an explanation of the benefits gained by having them.
That said, it's true that REST by itself doesn't tell you how to build an API. But all of that arguing about PUT/POST/PATCH, links here or there, etc, are mostly bikeshedding. It's like arguing for tabs vs spaces or whether the { should go inline or not. Just read the HTTP spec and then, when in doubt, just pick one and try to be consistent.
But you're right that many programmers don't deal well with that. It'd be nice to have some kind of reference protocol using HTTP & JSON and complying with REST, even if it would be as arbitrary as any other possible RESTful protocol.
Re: The Restful CookBook
#26Earlier quoted context omitted.
I usually use the term "REST" instead of RESTful - I know and understand the benefits of pure REST but I choose JSON over XML every time I can. Not to mention suboptimal support for PUT / DELETE / ... methods in Apache.
REST is an architectural pattern that specifies properties about the interface, not the data - how does using JSON over XML make your interface not RESTful? In his dissertation[1], Roy Fielding always refers to data in terms of resources rather than specific formats. [1] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
I think the idea that JSON isn't "REST" is because, unlike XML, it doesn't define links.
That said, JSON is just an encoding format. The actual response format is not "JSON", but the specific structure that your clients are expecting to receive (even if it is encoded in JSON), and that can certainly have links.
Re: The Restful CookBook
#27Having worked with hypermedia APIs recently I've come to appreciate how they feel more pragmatic and REST more pedantic. The hateos principle in particular lets you build thinner clients.
Re: The Restful CookBook
#28Earlier quoted context omitted.
> 404 should be reserved for URL/route errors. What dichotomy are you working off of here? It is absolutely a 404. How is this any less applicable to a DELETE request than it would be to a GET request for the same resource? What extra information would this new status status code carry? ---- > 10.4.5 404 Not Found > The server has not found anything matching the Request-URI. No indication is given of whether the cond…
Ok, so client requests "DELETE www.company.com/api/thing/1234" and gets a 404. Or even "GET www.company.com/api/thing/1234". Delete vs get doesn't matter. Did 1234 not exist, or is "/api/thing" the wrong path? 404 is overloaded. It can mean two very different things.
> Did 1234 not exist, or is "/api/thing" the wrong path?
This doesn't matter. You shouldn't be trying to pull "1234" out of the URI. The identifier for the resource as far as the client is concerned is the URI, not some numeric component buried within it. Just treat the URI as an opaque piece of information – if you get a 404, it's the wrong URI. If you're trying to divine meaning from the constituent parts of the URI, then you're almost certainly making a mistake.
Re: The Restful CookBook
#29Having worked with hypermedia APIs recently I've come to appreciate how they feel more pragmatic and REST more pedantic. The hateos principle in particular lets you build thinner clients.
Isn't "hypermedia API" just a new name some people came up with for "REST API" because the misunderstood non-HATEOAS mangling of REST is so common and they wanted to distinguish between the two? Real REST APIs use HATEOAS.
Re: The Restful CookBook
#30Earlier quoted context omitted.
I think some of the articles actually talk about json-hal and ld. Not sure about schema. The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. Please, if you have any idea's on how to improve the site, the whole idea was…
> The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. What exactly is the criteria of being a "hypermedia capable format"? The linked website gives an example of how the response on a bank-account like API might include…
> What exactly is the criteria of being a "hypermedia capable format"?
One document must be able to link to another.
> Is there a predefined way to deal with it in XML?
Yes, Xlink:
> In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose.
The problem with this is that it's non-standard and nothing understands it that isn't custom-written for that particular API.
> Though, honestly, that would seem to be the purpose of the "Link:" header.
Yes and no. Although the Link header is useful, it's not part of the document, it's a transport layer header. REST is transport-layer neutral.