The Restful CookBook
restcookbook.com
The Restful CookBook
1–10 of 53 posts
Re: The Restful CookBook
#2I 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, back in 2007, and which I've read cover to cover. Among other things, I said the overall goal should be to work with HTTP, not against it. Then their lead programmer tried to ask me what he apparently thought was a "trick" question. (He was quitting the startup to go back to school, and I was being hired to replace him.) He asked, if, for a given task, HTTP was too verbose a protocol, then what else might I use for a RESTful interface. I suppose that should have been my first warning. I wasn't sure what they were looking for, but I thought maybe they wanted me to say WebSockets, or perhaps they wanted me to push back against the question and ask why HTTP was too verbose, or they wanted me to suggest the use of TCP in an ad-hoc style that mimicked HTTP. I explored all those possible answers as I spoke with them.
Then I was hired and I started the job. Their system is not RESTful at all. The only HTTP verb they use is POST. They use it for everything, and they put all their data in the body of the POST. Their system is pure RPC, with a style influenced by SOAP.
The people I'm working with are in their early to mid 20s. I'm not sure if age is a factor, since I've seen the same mistake made by programmers in their 50s. But, for sure, there are some programmers who do not seem to know the difference between RPC and RESTful.
Of course, on a personal level, none of that really matters. I really like this place that I'm now working, and I'm happy to work with their RPC style. I have, however, insisted that we use correct terminology, just for the sake of clarity.
Re: The Restful CookBook
#3I 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,…
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.
Re: The Restful CookBook
#4I 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,…
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.
Re: The Restful CookBook
#5While 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 not official standards but allow you to write machine understandable and discoverable API.
If the author wants to promote standards, I think it would be better to look at what the world is using and then put together a guide that explains how to use JSON-LD and other W3C proposals.
Re: The Restful CookBook
#6It'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 idiosyncracies, the biggest offenders are JS folks complaining about how the DOM is implemented (disclaimer: I think it sucks too sometimes), yet these same circles champion things like "REST" and "HATEOAS" and "JSON API"...how are those things not part of "the Web"? Why do we only use "the Web" when we're pejoratively discussing it?
All that aside, this book seems relatively well-written. Good job guys!
Re: The Restful CookBook
#7Whenever I see a REST book I always have the same set of questions:
1) How do I call operations such as Clean, Restart etc not the regular CRUD ones? I may have to end up doing a variation of POST - is that RESTful (whatever that means)?
2) Whats a good way to simulate a "transaction" semantic (In as much as possible over a distributed systems with arbitrary nodes i.e. the Web)
3) How Do I call a long running operation- a create that takes more than a minute for example? Return a "tracking id" and keep GET querying?
4)How do I version my API? What is the one true way?
5)How about automated discovery of the API? Is it SWAGGER or WADL or something else?
6) Is a nested hierarchical URL scheme a good Idea? How much do you nest one resource under the other?
7) Are you a Teapot?
Many other questions that I have never seen answered properly
Re: The Restful CookBook
#8Whenever I see a REST book I always have the same set of questions: 1) How do I call operations such as Clean, Restart etc not the regular CRUD ones? I may have to end up doing a variation of POST - is that RESTful (whatever that means)? 2) Whats a good way to simulate a "transaction" semantic (In as much as possible over a distributed systems with arbitrary nodes i.e. the Web) 3) How Do I call a long running operati…
[deleted]
Re: The Restful CookBook
#9Whenever I see a REST book I always have the same set of questions: 1) How do I call operations such as Clean, Restart etc not the regular CRUD ones? I may have to end up doing a variation of POST - is that RESTful (whatever that means)? 2) Whats a good way to simulate a "transaction" semantic (In as much as possible over a distributed systems with arbitrary nodes i.e. the Web) 3) How Do I call a long running operati…
1,2,3) Strictly, they are all resources. A "Clean" resource can be created (POST|PUT) describing what to clean. It will create (201) that resource which you can read (get the status), even delete (cancel the action), or change (POST/PUT) again. Take a look at the http://restcookbook.com/Resources/asynchroneous-operations/, which basically describes this.
4) According to Roy Fielding, you don't (you don't version your website), but you can add/change/delete your resource versioning. I'd (and many) prefer the accept-header for this, but there are as many different versioning systems as there are API's.
5: hypermedia / HATEOAS
6: sure. If it makes sense. Not everything is hierarchical, but things that are, do it.
7: 418
The reason for this was figure out myself how certain things should be done in a "restful" way. To be honest, truly restful is an utopia imho, but on a daily basis, I see many advantages (as well explained in Roy fieldings dissertation) about the restful setup in comparision to a non-rest setup.
Pragmatically, since I'm not building API's for HUGE system (and even if they are or will become so), it's still possible to use non-rest components (yes, even verb-like systems and url versioning like /api/v1/.
I consider rest to be like the pirates code: not so much a strict law, but more as a guideline.
Re: The Restful CookBook
#10While 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 to set up a small set of articles which others could help out expanding. It turned out that not many people actually posted their idea's (or even complete posts), so what you see on the site is pretty much the same thing as 2-3 years ago. I'd love some more PR's on expanding with up-to-date technologies and techniques (even those who aren't truly restful)