Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Restful CookBook

restcookbook.com

Post reply on HN
Print view View original

11–20 of 53 posts

Re: The Restful CookBook

#11

Post by vdaniuk »

petrbela wrote: post #5

While 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…

Are you aware about anything resembling a convention or at least a limited consensus of best practices combining JSON Schema/Api with JSON-LD? That would be immensely useful.

Re: The Restful CookBook

#12

Post by aikah »

lisa_henderson wrote: post #2

I 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 appeal for RPC : No semantics , no arguing about whether one should use PUT, POST or PATCH and when , whether links should be headers or in the body, or about which JSON/XML bloated spec to use to make an API HATEOAS...

Re: The Restful CookBook

#13

Post by deathanatos »

jaytaph wrote: post #10
petrbela wrote: post #5

While 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…

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 links to other actions; XML and JSON seem equally capable here, as they can both encode links.

He mentions on another page,

> Unfortunately, JSON is not a hypermedia format. There is no predefined way to deal with link discovery in JSON.

Is there a predefined way to deal with it in XML? In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose.

Though, honestly, that would seem to be the purpose of the "Link:" header.

Re: The Restful CookBook

#14

Post by brudgers »

tomphoolery wrote: post #6

It's weird to me that a cookbook exists for this, though if it's helping people I have no problem with it. I'm just not sure why we think of "RESTful APIs" as anything other than using HTTP to its fullest capabilities. Even HATEOAS is really just "hey, shouldn't our APIs be as easy to navigate as the rest of the web?". I also find it ironic that there are lots of articles around condemning "the Web" for its idiosyncr…

This Software Engineering Radio podcast interview with Stefan Tilkov discusses the difference between REST and HTTP: http://www.se-radio.net/2008/05/episode-98-stefan-tilkov-on-...

It is from 2008 but probably more or less evergreen.

Re: The Restful CookBook

#15

Post by kzhahou »

Client sends a request to delete item #12345 from DB. The item does not exist in DB. Is that a 404, because the resource isn't found, or just generic 400? 404 should be reserved for URL/route errors.

We need a few new error codes for common REST operations.

Re: The Restful CookBook

#17

Post by jewbacca »

kzhahou wrote: post #15

Client sends a request to delete item #12345 from DB. The item does not exist in DB. Is that a 404, because the resource isn't found, or just generic 400? 404 should be reserved for URL/route errors. We need a few new error codes for common REST operations.

> 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 condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10...

Re: The Restful CookBook

#18

Post by kzhahou »

jewbacca wrote: post #17
kzhahou wrote: post #15

Client sends a request to delete item #12345 from DB. The item does not exist in DB. Is that a 404, because the resource isn't found, or just generic 400? 404 should be reserved for URL/route errors. We need a few new error codes for common REST operations.

> 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.

Re: The Restful CookBook

#19

Post by nearengine »

Drdrdrq wrote: post #4
mgkimsal wrote: post #3

Earlier quoted context omitted.

I've seen that, and even been "guilty" of it myself years ago - many people take 'RESTful' to just mean anything that returns JSON instead of a full HTML document.

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...

Re: The Restful CookBook

#20

Post by [deleted] »

kzhahou wrote: post #15

Client sends a request to delete item #12345 from DB. The item does not exist in DB. Is that a 404, because the resource isn't found, or just generic 400? 404 should be reserved for URL/route errors. We need a few new error codes for common REST operations.

[deleted]
Post reply on HN