7 ms·

The RESTful CookBook

129 points by bencevans 14y ago

glitchdout 14y ago
Cool idea. But it doesn't seem to be finished. Here's an example: http://restcookbook.com/Basics/loggingin/ http://restcookbook.com/Basics/loggingin/ Maybe it wasn't the author that submitted this? Or is the author asking for some help?
- bencevans 14y ago
  I'm not the author, but found it interesting and thought others may too. The site is on GitHub and seems to be in active development. GitHub: https://github.com/restcookbook/restcookbook https://github.com/restcookbook/restcookbook Authors/Contributors: https://github.com/restcookbook/restcookbook/contributors https://github.com/restcookbook/restcookbook/contributors
  - jaytaph 14y ago
    I'm the author, and yes: it's a cry for help :) I have too many projects that never gets off the ground, and hopefully this will trigger (at least some) developers to answer questions, or even ask them through a pull request. Furthermore: I don't pretend to know all the answers concerning REST, so I'm hoping this will trigger more people to contribute (it's either that, or people get annoyed by unanswered questions and just move on).
- 89vision 14y ago
  For me this is always the hardest part of REST. Do people use cookies for this?
  - jaytaph 14y ago
    For logging in. No. It's not the cookies that are the problem here, but the fact that such systems create stateful sessions which isn't what rest is about. There are some ways, for instance, using http authentication systems like http basis, digest, or more advanced systems like oauth(2) that can be used to let people "log in" into an API without loosing the stateless character of REST.. I will add this this to the recipe (hopefully) soon :)
  - mattdeboard 14y ago
    I'm trying it out where you send login json ('{"username": "foo", "password": "bar"}') to a special view, e.g. /api/v1/users/login/, and in return the client gets the user model and other related data in the response (assuming creds are valid). We also use a sessions to maintain state.
  - tom_b 14y ago
    I've chased the RESTful login/authentication around the web off and on when thinking about REST apis. It seems to boil down to two main approaches. 1 - follow the AWS API models, with a signed request using a private secret known only to the user and the server-side. You can see the S3 docs on RESTful auth using this approach. Also seems to recommend doing this over SSL. 2 - use SSL and send a userid/passwd or authentication key on each request. In general, cookies are regarded as one of those "makes it not restful" type things. I'd love to hear from HN'ers on how they handle RESTful authentication, particularly for projects where they are providing an API that is primarily consumed by a web app or other tool they implemented for users and have used RESTful api design as a design viewpoint.
    - philjackson 14y ago
      ApiAxle provides the first method with a hmac sha1 encoding of the current epoch, secret key and api key. http://apiaxle.com/docs/signing-requests/ http://apiaxle.com/docs/signing-requests/
  - tomlu 14y ago
    Short answer: Yes, you can use cookies, but not all systems support that (eg mobile apps). Here's what I do for that case: Create a /sessions endpoint and POST to that when you login. The session resource will include a token of some sort identifying the session securely. The client can then authenticate to the API by passing this token via an HTTP header.
Hydraulix989 14y ago
Spelling error on /Basics/hateoas/: "deposit" misspelled as "desposit" twice in the second XML code listing.
- jaytaph 14y ago
  Just fixed by a contributor. Thanks for the report!
GhotiFish 14y ago
http://restcookbook.com/Resources/pagination/ http://restcookbook.com/Resources/pagination/ "Even though it's tempting to create your own pagination scheme by "building" URLs, you should only use the information given by the API. This means, you cannot assume that the 3rd page can be found at /collection/3. If you do, your client will break as soon as the API changes its pagination behaviour." Is that a legitimate caveat? Are there clients that don't break when you change the API the client works with? Pretty smart clients.
- dustingetz 14y ago
  Consider a service powering a right click context menu. REST's HATEOAS constraint is a generalization of this idea - decoupling the API from the client. A lot of popular web APIs, e.g. Twitter, do not embrace HATEOAS, which is why API changes break clients. Which isn't really a big deal if you control all the clients.
  - shawn-butler 14y ago
    I've never fully bought into this constraint, I guess. I can understand how it might be useful for machine-to-machine consumption of an API (which seems to be a sort of holy grail) or for an API that is meant to last for say a decade and be self-documenting between generations of programmers. But I guess it seems like neither of those are domains where anyone I know is really working; admittedly entirely anecdotal. API seem to change or get replaced by "the next best thing" on the order of months or years. And doing HATEOAS seems like making a c++ program const-correct. Always starts out well but pretty soon isn't viewed as worthwhile by powers that be. Do you have an example of a really good HATEOAS public API that is widely consumed?
    - w0utert 14y ago
      >> And doing HATEOAS seems like making a c++ program const-correct. I would argue that cons-correctness is probably one of the most important considerations of any public C++ API, so not really the best analogy ;-). Try to refactor some actively used C++ framework API that never bothered about const correctness some day, weeks of fun and bickering with your API clients guaranteed.
drdaeman 14y ago
Many examples do not comply to HTTP standard at all, they're just schematic sketches. I mean, required headers are missing, response bodies are not separated from headers and so on. I believe, examples must be as real-world as possible. Say, the PATCH example must add at least an Content-Type header (and probably use RFC5261), otherwise an important aspect's lost.
- jaytaph 14y ago
  I think that's a good point. I will try and fix this, but the emphasis should be on the point we're trying to make with the recipe.
  - drdaeman 14y ago
    I think, the important aspects could be highlighted. Although I'm not sure Markdown allows, say, bold text chunks, in code blocks.
weixiyen 14y ago
Is my API RESTful when I use (only) JSON? NO. There is no predefined way to deal with link discovery in JSON. :(
- rdtsc 14y ago
  It is kind of silly. Just add a reasonable convention and stick to it. {'href':'<url>', 'rel':'<linktype'} or something like that. Saying to throw away your JSON representation because you can't do links is ridiculous.
  - steveklabnik 14y ago
    Once you add extra stuff, it's not JSON any more. If you pick a convention, document it, and then serve it as some other type ( like application/foo+json ) then you're good. It's true that there's no reason to throw away the _serialization_ format that JSON provides you, but if you serve application/json, then you can't have extra 'conventions.'
    - rdtsc 14y ago
      Presumably what you serve is not random JSON, it is already application specific in some ways (unless it is proxying or encapsulating other services, which is reasonable). So say there will already be conventions about how to service collections (/carts/ that will be an array of objects that look a certain way or or single items /carts/<carid>/ that is an individual shopping cart may represented as a single json object with some known keys and values). So having links and relationships is just another such convention isn't it? How is linking now special in the sense that it can't be considered bona-fide JSON, if it is parsed by a JSON parser without error just like a shopping cart it. Yeah I am not sure how important it is to say that I am serving applicaiton/foo+json or just application/json? I have been doing just application/json lately, I may very well be wrong about it.
      - icebraining 14y ago
        I'm a big REST fan, but I think using a different mediatype is only important if the format is (or can become) generic and used by other services. For example, if you're serving a GeoJSON document, which is a open format used by many services, it makes sense to use a specific mediatype. If, on the other hand, the format is totally custom to your service, I don't really see the point, since the client parsing it must be custom too. The only advantage I can see to using custom mediatypes is if you want to do versioning (+v1, +v2, etc).
achacha 14y ago
PURGE is probably never used (and in my 5 years of log analysis I have never seen it with any major API, but I am sure someone uses it, but why design for such a small fringe) and it is also not part of the HTTP (RFC-2616, section 9: https://www.ietf.org/rfc/rfc2616.txt https://www.ietf.org/rfc/rfc2616.txt) spec so why design for it, just asking for trouble; stick to 'modified'-type headers to control the cache and HTTP response 304 when needed. While XML is ok, JSON is the dominant format for REST APIs and consumed by way more frameworks and libraries at this point. Was this written 10 years ago, it seems kind of stale and confusing.
evv 14y ago
http://restcookbook.com/Basics/hateoas/ http://restcookbook.com/Basics/hateoas/ - What is HATEOAS and why is it important for my REST API? This page doesn't even try to explain why HATEOAS is important. And I'm not sure that it is. This example uses some arbitrary xml to describe the API, but if no client can consistently read and understand it, what purpose does it serve?

129 points by bencevans 14y ago

Cool idea. But it doesn't seem to be finished. Here's an example: http://restcookbook.com/Basics/loggingin/ http://restcookbook.com/Basics/loggingin/ Maybe it wasn't the author that submitted this? Or is the author asking for some help?

bencevans 14y ago
I'm not the author, but found it interesting and thought others may too. The site is on GitHub and seems to be in active development. GitHub: https://github.com/restcookbook/restcookbook https://github.com/restcookbook/restcookbook Authors/Contributors: https://github.com/restcookbook/restcookbook/contributors https://github.com/restcookbook/restcookbook/contributors
- jaytaph 14y ago
  I'm the author, and yes: it's a cry for help :) I have too many projects that never gets off the ground, and hopefully this will trigger (at least some) developers to answer questions, or even ask them through a pull request. Furthermore: I don't pretend to know all the answers concerning REST, so I'm hoping this will trigger more people to contribute (it's either that, or people get annoyed by unanswered questions and just move on).
89vision 14y ago
For me this is always the hardest part of REST. Do people use cookies for this?
- jaytaph 14y ago
  For logging in. No. It's not the cookies that are the problem here, but the fact that such systems create stateful sessions which isn't what rest is about. There are some ways, for instance, using http authentication systems like http basis, digest, or more advanced systems like oauth(2) that can be used to let people "log in" into an API without loosing the stateless character of REST.. I will add this this to the recipe (hopefully) soon :)
- mattdeboard 14y ago
  I'm trying it out where you send login json ('{"username": "foo", "password": "bar"}') to a special view, e.g. /api/v1/users/login/, and in return the client gets the user model and other related data in the response (assuming creds are valid). We also use a sessions to maintain state.
- tom_b 14y ago
  I've chased the RESTful login/authentication around the web off and on when thinking about REST apis. It seems to boil down to two main approaches. 1 - follow the AWS API models, with a signed request using a private secret known only to the user and the server-side. You can see the S3 docs on RESTful auth using this approach. Also seems to recommend doing this over SSL. 2 - use SSL and send a userid/passwd or authentication key on each request. In general, cookies are regarded as one of those "makes it not restful" type things. I'd love to hear from HN'ers on how they handle RESTful authentication, particularly for projects where they are providing an API that is primarily consumed by a web app or other tool they implemented for users and have used RESTful api design as a design viewpoint.
  - philjackson 14y ago
    ApiAxle provides the first method with a hmac sha1 encoding of the current epoch, secret key and api key. http://apiaxle.com/docs/signing-requests/ http://apiaxle.com/docs/signing-requests/
- tomlu 14y ago
  Short answer: Yes, you can use cookies, but not all systems support that (eg mobile apps). Here's what I do for that case: Create a /sessions endpoint and POST to that when you login. The session resource will include a token of some sort identifying the session securely. The client can then authenticate to the API by passing this token via an HTTP header.

Hydraulix989 14y ago

Spelling error on /Basics/hateoas/: "deposit" misspelled as "desposit" twice in the second XML code listing.

jaytaph 14y ago
Just fixed by a contributor. Thanks for the report!

GhotiFish 14y ago

http://restcookbook.com/Resources/pagination/ http://restcookbook.com/Resources/pagination/ "Even though it's tempting to create your own pagination scheme by "building" URLs, you should only use the information given by the API. This means, you cannot assume that the 3rd page can be found at /collection/3. If you do, your client will break as soon as the API changes its pagination behaviour." Is that a legitimate caveat? Are there clients that don't break when you change the API the client works with? Pretty smart clients.

dustingetz 14y ago
Consider a service powering a right click context menu. REST's HATEOAS constraint is a generalization of this idea - decoupling the API from the client. A lot of popular web APIs, e.g. Twitter, do not embrace HATEOAS, which is why API changes break clients. Which isn't really a big deal if you control all the clients.
- shawn-butler 14y ago
  I've never fully bought into this constraint, I guess. I can understand how it might be useful for machine-to-machine consumption of an API (which seems to be a sort of holy grail) or for an API that is meant to last for say a decade and be self-documenting between generations of programmers. But I guess it seems like neither of those are domains where anyone I know is really working; admittedly entirely anecdotal. API seem to change or get replaced by "the next best thing" on the order of months or years. And doing HATEOAS seems like making a c++ program const-correct. Always starts out well but pretty soon isn't viewed as worthwhile by powers that be. Do you have an example of a really good HATEOAS public API that is widely consumed?
  - w0utert 14y ago
    >> And doing HATEOAS seems like making a c++ program const-correct. I would argue that cons-correctness is probably one of the most important considerations of any public C++ API, so not really the best analogy ;-). Try to refactor some actively used C++ framework API that never bothered about const correctness some day, weeks of fun and bickering with your API clients guaranteed.

drdaeman 14y ago

Many examples do not comply to HTTP standard at all, they're just schematic sketches. I mean, required headers are missing, response bodies are not separated from headers and so on. I believe, examples must be as real-world as possible. Say, the PATCH example must add at least an Content-Type header (and probably use RFC5261), otherwise an important aspect's lost.

jaytaph 14y ago
I think that's a good point. I will try and fix this, but the emphasis should be on the point we're trying to make with the recipe.
- drdaeman 14y ago
  I think, the important aspects could be highlighted. Although I'm not sure Markdown allows, say, bold text chunks, in code blocks.

weixiyen 14y ago

Is my API RESTful when I use (only) JSON? NO. There is no predefined way to deal with link discovery in JSON. :(

rdtsc 14y ago
It is kind of silly. Just add a reasonable convention and stick to it. {'href':'<url>', 'rel':'<linktype'} or something like that. Saying to throw away your JSON representation because you can't do links is ridiculous.
- steveklabnik 14y ago
  Once you add extra stuff, it's not JSON any more. If you pick a convention, document it, and then serve it as some other type ( like application/foo+json ) then you're good. It's true that there's no reason to throw away the _serialization_ format that JSON provides you, but if you serve application/json, then you can't have extra 'conventions.'
  - rdtsc 14y ago
    Presumably what you serve is not random JSON, it is already application specific in some ways (unless it is proxying or encapsulating other services, which is reasonable). So say there will already be conventions about how to service collections (/carts/ that will be an array of objects that look a certain way or or single items /carts/<carid>/ that is an individual shopping cart may represented as a single json object with some known keys and values). So having links and relationships is just another such convention isn't it? How is linking now special in the sense that it can't be considered bona-fide JSON, if it is parsed by a JSON parser without error just like a shopping cart it. Yeah I am not sure how important it is to say that I am serving applicaiton/foo+json or just application/json? I have been doing just application/json lately, I may very well be wrong about it.
    - icebraining 14y ago
      I'm a big REST fan, but I think using a different mediatype is only important if the format is (or can become) generic and used by other services. For example, if you're serving a GeoJSON document, which is a open format used by many services, it makes sense to use a specific mediatype. If, on the other hand, the format is totally custom to your service, I don't really see the point, since the client parsing it must be custom too. The only advantage I can see to using custom mediatypes is if you want to do versioning (+v1, +v2, etc).

achacha 14y ago

PURGE is probably never used (and in my 5 years of log analysis I have never seen it with any major API, but I am sure someone uses it, but why design for such a small fringe) and it is also not part of the HTTP (RFC-2616, section 9: https://www.ietf.org/rfc/rfc2616.txt https://www.ietf.org/rfc/rfc2616.txt) spec so why design for it, just asking for trouble; stick to 'modified'-type headers to control the cache and HTTP response 304 when needed. While XML is ok, JSON is the dominant format for REST APIs and consumed by way more frameworks and libraries at this point. Was this written 10 years ago, it seems kind of stale and confusing.

evv 14y ago

http://restcookbook.com/Basics/hateoas/ http://restcookbook.com/Basics/hateoas/ - What is HATEOAS and why is it important for my REST API? This page doesn't even try to explain why HATEOAS is important. And I'm not sure that it is. This example uses some arbitrary xml to describe the API, but if no client can consistently read and understand it, what purpose does it serve?