8 ms·

Nice one! Good on you for building a thing and putting it out there. A few comments/suggestions: * You have DEBUG = True in your production Django config. (eg

by hartror 11y ago

Nice one! Good on you for building a thing and putting it out there. A few comments/suggestions: * You have DEBUG = True in your production Django config. (eg. http://deckofcardsapi.com/api/ http://deckofcardsapi.com/api/) * You are mutating state with HTTP GET, this is an anti-pattern for a number of reasons. The common one I use with people I coach is that browsers/proxies will happily cache GET requests unless told not to, but there are a number of other reasons if you read up on REST [1]. * Being a public API in a well known domain this is a good opportunity to make the API self documenting & navigable with a hypermedia format. (eg HAL, Siren, JSON-LD) [2] [1] http://martinfowler.com/articles/richardsonMaturityModel.html http://martinfowler.com/articles/richardsonMaturityModel.htm... [2] http://sookocheff.com/posts/2014-03-11-on-choosing-a-hypermedia-format/ http://sookocheff.com/posts/2014-03-11-on-choosing-a-hyperme...

voltagex_ 11y ago
>good opportunity to make the API self documenting & navigable with a hypermedia format. (eg HAL, Siren, JSON-LD) Other than learning, what's the benefit here?
- hartror 11y ago
  I assume you mean what is the benefit of hypermedia? Martin Fowler does a good job explaining it (http://martinfowler.com/articles/richardsonMaturityModel.html#level3 http://martinfowler.com/articles/richardsonMaturityModel.htm...). As does Mike Amundsen (http://www.infoq.com/presentations/Building-Hypermedia-API http://www.infoq.com/presentations/Building-Hypermedia-API).
  - iamflimflam1 11y ago
    I don't see much benefit in martin fowler's example <openSlotList> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"> <link rel = "/linkrels/slot/book" uri = "/slots/1234"/> </slot> <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"> <link rel = "/linkrels/slot/book" uri = "/slots/5678"/> </slot> </openSlotList> Each slot now has a link element which contains a URI to tell us how to book an appointment. Well, not really - we can only guess that by the fact that the link ends in "book". We also don't know if we are supposed to GET, PUT, DELETE, POST.. or what data we are supposed to send to the url to actually make the booking.
    - hartror 11y ago
      I agree though I expect Fowler may argue that that is what the HTTP verb OPTIONS is for. Amundsen on the other hand likes his hypermedia more explicit and I tend to agree with him.
    - evanspa 11y ago
      Clients of a hypermedia REST API are supposed to have a priori knowledge of the link relations (the "rel" attribute). The fact the rel in this example looks like a URI is sometimes used as a convention (i.e., if the API supports it, a client may do a GET against the rel value, and get back a human-readable description of the purpose of the rel). In the human readable description of the "/linksrels/slot/book" link relation, information should be given about what generally can be done with such links (like if GET or POST is supported, etc). This allows you to build your client applications. The value of the actual link (the 'uri' attribute) should be completely opaque to the client.
Kiro 11y ago
> You are mutating state with HTTP GET I agree. However, this is the first API I've seen where a mutable GET actually makes sense. Drawing a card is definitely a GET. How would you do it instead?
- anilgulecha 11y ago
  A PUT would work, with action=draw&count=2, or action=shuffle, and so forth.
  - kikibobo69 11y ago
    PUT should be idempotent, though.
    - bdcravens 11y ago
      Could each draw return a draw_hash, that is usable only once? Not only could you then have idempotent draws, you could easily embed it as hypermedia,a previous hash could be sent to a hand_history to return an array of point in time data
  - nl 11y ago
    As a general rule "action" parameter is pretty non-RESTful. Sometimes RPC-style interfaces like that are ok, but don't pretend that they are RESTful. Also PUTs are supposed to be idempotent, so don't use a PUT for this.
    - dghf 11y ago
      I thought URLs (including query strings) were opaque under REST?
      - vog 11y ago
        URLs are opaque, but the meanings of the HTTP methods aren't.
iamleppert 11y ago
1. His documentation is better than HAL, Siren, JSON-LD. It's a nice page. 2. GET makes sense here. If anything, it would be a PATCH. But it's silly to get bogged down in details.
- vog 11y ago
  > 2. GET makes sense here. If anything, it would be a PATCH. But it's silly to get bogged down in details. Those "details" are quite important, as already explained in several other comments: https://news.ycombinator.com/item?id=9523225 https://news.ycombinator.com/item?id=9523225 https://news.ycombinator.com/item?id=9523106 https://news.ycombinator.com/item?id=9523106 https://news.ycombinator.com/item?id=9523075 https://news.ycombinator.com/item?id=9523075 https://news.ycombinator.com/item?id=9523066 https://news.ycombinator.com/item?id=9523066 https://news.ycombinator.com/item?id=9525568 https://news.ycombinator.com/item?id=9525568

by hartror 11y ago

voltagex_ 11y ago

>good opportunity to make the API self documenting & navigable with a hypermedia format. (eg HAL, Siren, JSON-LD) Other than learning, what's the benefit here?

hartror 11y ago
I assume you mean what is the benefit of hypermedia? Martin Fowler does a good job explaining it (http://martinfowler.com/articles/richardsonMaturityModel.html#level3 http://martinfowler.com/articles/richardsonMaturityModel.htm...). As does Mike Amundsen (http://www.infoq.com/presentations/Building-Hypermedia-API http://www.infoq.com/presentations/Building-Hypermedia-API).
- iamflimflam1 11y ago
  I don't see much benefit in martin fowler's example <openSlotList> <slot id = "1234" doctor = "mjones" start = "1400" end = "1450"> <link rel = "/linkrels/slot/book" uri = "/slots/1234"/> </slot> <slot id = "5678" doctor = "mjones" start = "1600" end = "1650"> <link rel = "/linkrels/slot/book" uri = "/slots/5678"/> </slot> </openSlotList> Each slot now has a link element which contains a URI to tell us how to book an appointment. Well, not really - we can only guess that by the fact that the link ends in "book". We also don't know if we are supposed to GET, PUT, DELETE, POST.. or what data we are supposed to send to the url to actually make the booking.
  - hartror 11y ago
    I agree though I expect Fowler may argue that that is what the HTTP verb OPTIONS is for. Amundsen on the other hand likes his hypermedia more explicit and I tend to agree with him.
  - evanspa 11y ago
    Clients of a hypermedia REST API are supposed to have a priori knowledge of the link relations (the "rel" attribute). The fact the rel in this example looks like a URI is sometimes used as a convention (i.e., if the API supports it, a client may do a GET against the rel value, and get back a human-readable description of the purpose of the rel). In the human readable description of the "/linksrels/slot/book" link relation, information should be given about what generally can be done with such links (like if GET or POST is supported, etc). This allows you to build your client applications. The value of the actual link (the 'uri' attribute) should be completely opaque to the client.

Kiro 11y ago

> You are mutating state with HTTP GET I agree. However, this is the first API I've seen where a mutable GET actually makes sense. Drawing a card is definitely a GET. How would you do it instead?

anilgulecha 11y ago
A PUT would work, with action=draw&count=2, or action=shuffle, and so forth.
- kikibobo69 11y ago
  PUT should be idempotent, though.
  - bdcravens 11y ago
    Could each draw return a draw_hash, that is usable only once? Not only could you then have idempotent draws, you could easily embed it as hypermedia,a previous hash could be sent to a hand_history to return an array of point in time data
- nl 11y ago
  As a general rule "action" parameter is pretty non-RESTful. Sometimes RPC-style interfaces like that are ok, but don't pretend that they are RESTful. Also PUTs are supposed to be idempotent, so don't use a PUT for this.
  - dghf 11y ago
    I thought URLs (including query strings) were opaque under REST?
    - vog 11y ago
      URLs are opaque, but the meanings of the HTTP methods aren't.

iamleppert 11y ago

1. His documentation is better than HAL, Siren, JSON-LD. It's a nice page. 2. GET makes sense here. If anything, it would be a PATCH. But it's silly to get bogged down in details.

vog 11y ago
> 2. GET makes sense here. If anything, it would be a PATCH. But it's silly to get bogged down in details. Those "details" are quite important, as already explained in several other comments: https://news.ycombinator.com/item?id=9523225 https://news.ycombinator.com/item?id=9523225 https://news.ycombinator.com/item?id=9523106 https://news.ycombinator.com/item?id=9523106 https://news.ycombinator.com/item?id=9523075 https://news.ycombinator.com/item?id=9523075 https://news.ycombinator.com/item?id=9523066 https://news.ycombinator.com/item?id=9523066 https://news.ycombinator.com/item?id=9525568 https://news.ycombinator.com/item?id=9525568