News for hackers. Stuff that matters.
Re:Show HN: Deck of Cards – A playing card API by vladharbuz on Monday May 11, 2015 @04:36AM (#9523365)
Some of these don't really make sense.

    POST /decks/<id>/draw : returns a url to a card
    POST /decks/<id>/shuffle : returns a url to the deck
Are you adding a "draw" to deck <id>?

    POST /cards : returns a url to a card (post body having deck id)
    POST /shuffles : returns a url to the deck (post body having deck id)
Are you creating a card or a shuffle?

Here's how things should be, in my opinion:

    DELETE /deckCard/<deckId>
This removes a card from an abstract entity representing the relation between decks and cards. Thus, it draws a card and returns it, sort of like popping something off a stack.

    PUT /decks/<id> with body {shuffle: true}
This edits the abstract "shuffle" attribute of deck <id>, shuffling the deck. This is indeed odd, but I'm afraid it's the best you can do for a mutating request. I would recommend a non-mutating request that makes a new deck out of an old deck, perhaps using "source" as an abstract attribute.

    POST /decks with body {source: <oldId>}
It just goes to show that while REST is a good standard for CRUD operations, and is surprisingly extensible for non-CRUD operations, it can get confusing and become a real pain. Should one just deal with it or move to e.g. RPC? I haven't figured this out.
Re:Show HN: Deck of Cards – A playing card API by hartror on Monday May 11, 2015 @04:52AM (#9523405)
Just because a thing, such as a draw or a shuffle isn't a physical thing doesn't mean it cannot exist as resource. Programming is all about creating abstractions, so why cannot I create a shuffle or a draw resource? I could even record them and share them on their own endpoints for clients to view.

Commenting directly on you suggestions:

    DELETE /deckCard/<deckId>
This means each DELETE on this url would result in a different deck state which isn't idempotent as DELETE is mean to be.

    PUT /decks/<id> with body {shuffle: true}
Same with this, the resource would end up in a new state each time making it unsafe to do repeatedly as the HTTP spec says.

I think the issue is REST is taught with a CRUD view point and people have difficulty thinking about it in other ways. Also the English meanings of the HTTP verbs get confused with their HTTP meanings which doesn't help.

I liked this blog post which talks about the concept of "REST without PUT".

http://www.thoughtworks.com/insights/blog/rest-api-design-re...

edit: you've edited you comment since I started my reply:

I like your idea of replacing shuffle with a new deck:

    POST /decks with body {source: <oldId>}
You could then do things like lock the source deck which would make it easier to implement a multi-client system where you cannot draw from a deck until you have been informed it has been shuffled.
Re:Show HN: Deck of Cards – A playing card API by vladharbuz on Monday May 11, 2015 @04:59AM (#9523422)
I agree with your comments and take them as evidence that REST is exceedingly difficult and complex for these use cases.

You can create new resources, just as I have, it just doesn't make sense to "POST /cards" when you're not making a new card at all.