Show HN: Deck of Cards – A playing card API

Thought about that as soon as I saw it returning rasters. SVG would be best offered alongside as an option; it requires more effort to use than just a png. Perhaps a 'vector' to accompany each 'image'?

voltagex_3• 11 years ago

Accept: headers. Default to image/png

evv• 11 years ago

Those cards look great! Much better than the OP's raster images.

But they seem familiar. I can't help but wonder, are they infringing on any copyrights?

jessaustin2• 11 years ago

Following that link, the first section on the page:

These poker sized cards have been created and hand optimized in various vector formats (.eps and .svg) using the open source .svg graphics editor Inkscape http://www.inkscape.org.

....

Generally, this means the cards are free to use (commercially and non commercially) but must be properly attributed (see "README.txt" file) and (The library itself, not your project) re-distributed only under the same license.

polshaw• 11 years ago

I used the unicode symbols; ♠ etc for my game; http://playonline.cards

It was a bit fiddly but definitely wins on file size. I would have used SVG for the face cards but they really killed performance with animation unfortunately, so I went with a compressed PNG (20kb for all 3).

hartror10• 11 years 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/)

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

[2] http://sookocheff.com/posts/2014-03-11-on-choosing-a-hyperme...

voltagex_3• 11 years 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?

hartror10• 11 years ago

I assume you mean what is the benefit of hypermedia?

Martin Fowler does a good job explaining it (http://martinfowler.com/articles/richardsonMaturityModel.htm...).

As does Mike Amundsen (http://www.infoq.com/presentations/Building-Hypermedia-API).

Kiro• 11 years 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• 11 years ago

A PUT would work, with action=draw&count=2, or action=shuffle, and so forth.

xnxn• 11 years ago

Drawing a card is definitely a GET.

I see where you're coming from ("I'm drawing / taking / GETting some cards"), but drawing cards is not an idempotent action. I would implement it as a POST.

crimsonalucard• 11 years ago

Why conform to arbitrary conventions when they don't make sense? Personally I think the best reason to conform to REST is because the user expects a "good" api to conform. Other then that is there any hard reason as to why it's "better" to strictly follow REST or even follow it at all?

Is an api that is consistent, fast and documented well, but uses only GET requests for everything including state changes really a horrible api?

Drakim• 11 years ago

I would argue that "drawing a card" isn't merely an information look up (GET) but an action with consequences (POST).

Looking at the cards in your hands, if the server maintains your hand state, would be a GET though.

hartror10• 11 years ago

As others have pointed out the HTTP verbs have meaning at a protocol level, trying to match a verb based on its English meaning is fraught with problems. Not least of which is the proxy problem I pointed out in my original comment.

jalfresi7• 11 years ago

DELETE a card from the deck. Return the card(s) drawn in the response body. Have a separate resource for the top of the deck:

DELETE /api/<deck-id>/top?count=2

------

200 Ok

8♣

10♥

thedufer• 11 years ago

It is acceptable for a client to retry a request that failed if it is a GET. This could happen if the server got your request but the response got lost, in which case you can't count on the deck having the right number of cards.

iamleppert• 11 years 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.

vog4• 11 years 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=9523106

https://news.ycombinator.com/item?id=9523075

https://news.ycombinator.com/item?id=9523066

https://news.ycombinator.com/item?id=9525568

adanto6840• 11 years ago

What's being used for RNG?

Walkman• 11 years ago

https://github.com/crobertsbmw/deckofcards/blob/master/deck/...

sirclueless2• 11 years ago

Appears to be python's random module, so not very secure if that's what you're after but it's probably correctly pseudorandom: https://github.com/crobertsbmw/deckofcards/blob/master/deck/...

sneak• 11 years ago

Doesn't matter, as the whole thing is served without TLS.

hurin2• 11 years ago

Seriously, why wouldn't you just use a local RNG? Do you realize it's actually less work than reading API documentation?

crobertsbmw11• 11 years ago

Consider it a bad Rube Goldberg Machine.

hurin2• 11 years ago

  numbers = ['2','3','4','5','6','7','8','9','10','J','K','Q','A']
  suits = ['CLUBS', 'SPADES', 'HEARTS', 'DIAMONDS']
  deck = [(num,suit) for num in numbers for suit in suits]
  random.shuffle(deck)
  draw_card = lambda deck: deck.pop()

packetized• 11 years ago

Is something new with this project? I believe this same thing was posted 10 days ago.

https://news.ycombinator.com/item?id=9462184

Would be interesting to hear if some of the issues raised in the previous submission were fixed or updated.

flashman• 11 years ago

I'm not sure what this file does: https://github.com/crobertsbmw/deckofcards/blob/master/list....

sturmeh• 11 years ago

(ಠ_ಠ)

fosk• 11 years ago

Remember to always gitignore your list.txt file folks!

crobertsbmw11• 11 years ago

Good catch, haha.

ChristianBundy• 11 years ago

https://github.com/crobertsbmw/deckofcards/pull/3

bdcravens2• 11 years ago

That of course doesn't delete it from the history :-)

You can do that via https://help.github.com/articles/remove-sensitive-data/, but once it's been cloned, the file is of course out of the toothpaste tube so to speak :-)

ctekin• 11 years ago

Also unfortunate : https://github.com/crobertsbmw/deckofcards/blob/fb02c09b9bc4...

crobertsbmw11• 11 years ago

I've changed the secret key that I am using in production. I wanted the settings.py to be there so it works out of the box if anyone forks it.

evan_• 11 years ago

If it supported the idea of multiple players, keeping track of what cards each player has, and facilitating passing cards between players; it could be a cool backend for lots of different card games.

sirclueless2• 11 years ago

I wonder if you could do most of this cryptographically. If you did, you could make a client that could do all of this peer-to-peer. I think you would just need the following to make a wide range of games (many popular ones, perhaps most?):

1. Client can produce a signature that it drew the k'th card from the deck for any k.

2. Client can produce a signature that the k'th card is X if it drew the k'th card.

3. Client can produce a signature that card X came from any arbitrary set of card indices containing k if it drew the k'th card. (This is the hardest one.) If it's easier, you could get most of this even restricting it to sets of cards that the client has drawn.

With just that, I bet you could make a protocol for most card games where no one can cheat, where the central server's role is only to give out information about k'th card one and only one time. Certainly it's enough for blackjack, most forms of poker, hearts, and go fish. Anyone have a game that would be difficult? Maybe one where hidden cards get passed from player to player.

crobertsbmw11• 11 years ago

I don't know much about cryptography. But this is very intriguing to me.

lann• 11 years ago

You can! http://en.m.wikipedia.org/wiki/Mental_poker

jonobird1• 11 years ago

I'm just getting a "400 Bad Request" for the home page (from Brisbane, Australia)

bt3• 11 years ago

Seconded. US here.

crobertsbmw11• 11 years ago

Sorry about that. Should be fixed now.

crobertsbmw11• 11 years ago

Fixed.

recursive• 11 years ago

HTTP errors as a service

crobertsbmw11• 11 years ago

Fixed.

mattkenefick• 11 years ago

Looks good.

xxbondsxx• 11 years ago

Pretty cool! Love that theres no authentication and I can start straight from curl.

Nit: drawing from an empty deck does not throw an error:

curl http://deckofcardsapi.com/api/draw/i763hn8lcg0e/

{"remaining": 0, "cards": [], "deck_id": "i763hn8lcg0e", "success": true}

As does drawing a comically large number of cards:

http://deckofcardsapi.com/api/draw/vzlem7q4jhna/?count=10000...;

(...) "success": true}\n

bloodspatter504• 11 years ago

Can someone show or explain:

1. An example of how this could be used.

2. How to do something other than just shuffling the cards.

d0m2• 11 years ago

I think it was just a fun side project. But as to how it could be used.. just a few weeks ago we were at a hackathon and built a quick poker texas holdem game. A library like that (arguably a bit more comprehensive) would have saved us a few hours.

MeghdeepRay• 11 years ago

Was it just a texas hold em ? Or a variation of it ? I assume being a hackathon it wasn't a vanilla texas hold em. Could you provide some more details and maybe the code ? After seeing this I'm interested to know what else you've done.

soup10• 11 years ago

I like the website design but shuffling cards is extremely trivial to code. Also cards are mostly used for gambling games and it's a huge security hole to use a third party api for that unless it's from a very trustworthy source.

One maybe useful thing about this api is the card images, but there are also probably plenty of decks in the public domain.

nly• 11 years ago

Also cards are mostly used for gambling games and it's a huge security hole to use a third party api

Depends. If you're writing a game you wanted the player to trust you might want to use an external shuffling service so you can easily show proof-of-deck after the game is over.

Of course, you could do this simply by giving the player a cryptographic hash of the shuffled deck beforehand, e.g. SHA-256(5H,4D,AS...)

ivanche2• 11 years ago

I've worked as a developer for online gambling games for 6 years. We never shuffled the deck of cards. Instead, as player requests another card(s), they are generated using hardware RNG and returned to player. Deck only knows which cards are left in it, but their order is undefined until that call to RNG.

gabemart• 11 years ago

This seems like a really cool project!

But how are you shuffling the cards, and how are you identifying unique shuffled decks?

It looks like the deck_id is 12 characters, numbers or lower-case letters. That gives a range of 36^12 or around 4.7 * 10^18. The total range of a physical deck of shuffled cards is 52! or around 8 * 10^67.

It's possible I have misunderstood what deck_id is for.

kornish• 11 years ago

Looks like deck_id references a persisted model: https://github.com/crobertsbmw/deckofcards/blob/master/deck/...

The model stores the state of the deck, including things like order and remaining cards and how many "decks" of 52 cards are in play.

carrotleads• 11 years ago

Sounds straightforward and simple. Well done.

Would like an option to set parameters of a deck. Some card games use only 8 cards from a set and not the whole 13.

comrh• 11 years ago

Adding and subtracting from the starting deck would very useful. Adding Jokers, playing with only 1-10 (scopa), ect

drinchev• 11 years ago

Wow. I never thought this could be an API. Really good work. I remember I spent a lot of time developing a class that deals with a deck of cards, shuffle and associate the card with a png.

I would use this API in the future.

alangpierce• 11 years ago

While this looks to me like a pretty clean and straightforward API, it's definitely not a REST API (not that it claims to be):

* The API doesn't really follow HTTP. It allows GET for state-modifying actions, which breaks assumptions that could be made by browsers, client libraries, caches, and proxies. Also, the "success" field seems fishy; a 200 response code is the usual HTTP way to indicate success.

* The API is not resource-oriented; the URLs "shuffle" and "draw" are verbs that describe the action to take. In a "real" REST API, URLs define conceptual resources (nouns), and you interact with the API by interacting with those resources.

* The API does not use hypermedia.

Hypermedia and HTTP compliance are discussed elsewhere in this thread, but I wonder if others have an opinion on the fact that the API isn't resource-oriented.

This "resource-oriented" rule has always bugged me about REST APIs. My impression has been that REST advocates claim that pretty much every API can and should be implemented with a CRUD-like interface (where the entire API consists of performing GET, POST, PUT, and DELETE on a conceptual set of resources), but it seems like that would be really awkward for this "deck of cards" use case. Is there value in trying to use resources here? What might it look like?

salex892• 11 years ago

Not that I had a similar situation, but how to implement actions such as shuffle or draw and make them-resource like?

SilasX• 11 years ago

I guess shuffles and draws should be their own resources, and you POST to it to do that action? You'd then keep a table of shuffle/draw events, which mutate the deck as a side effect.

hartror10• 11 years ago

Resource oriented and its implication of nouns as opposed to verbs doesn't have to equal CRUD. I can see a case for bending the nouns rule of thumb in this domain, for example I might have an api like so:

    POST /decks : returns a url to a new deck
    GET  /decks/<id> : returns a deck
    POST /decks/<id>/draw : returns a url to a card
    POST /decks/<id>/shuffle : returns a url to the deck
    GET  /cards/<id> : returns a card drawn from a deck

The draw/shuffle verbs arguably could be implemented like this:

    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)

The cards POST makes a lot of sense, now that I look at it I think I would use that interface. And you could argue that the shuffles resource makes sense as at some point you may want to record and share when someone shuffles the deck.

vladharbuz3• 11 years ago

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.

thetrav• 11 years ago

I would approach it from a little further away conceptually.

A deck only makes sense in the context of a game, a draw only makes sense in the context of moving the card from the deck to some other container (hand, discard pile, arbitrary pile on the table).

I also like to model games as sequential actions (because that's how they work) so my API would be more like:

GET /game/<id>/turn/<index>/decks/<id>/card/<index> <- 1 or 0 for top card, other numbers to view more than one

Then your draw action is a move the card from the deck to one of the other places, either with a POST to the new place, that redirects you to the next turn of that place, or with a PUT to the card itself if you have some "location" field on the card that can be updated.

The question that strikes me though, is whether it makes sense at all for a client to be controlling the draw in a game of CaH, as it's not an optional step. Why not just have the model automatically put cards back in the players hands when they make their moves?

geon3• 11 years ago

I like my REST interfaces, but they only really fit CRUD-like situations. Sometimes, you will want to be less restful to optimize for some real world issue, most likely latency.

I suppose it is a bit like de-normalizing your database for performance.

For a situation like this, I would keep it as restful as practically possible. Since the shuffle mutates the state, it should be a post/put. Since it doesn't create a new resource,you could argue it should be put, but you don't have new data anyway, so the point is kind of moot.

I'd probably collect my custom verbs behind a common path to make it more clear, like

    /api/decks/mydeckid/verbs/shuffle

Or to make it stand out more:

    /api/decks/mydeckid?verb=shuffle

The response would use http error/success codes like any rest interface.

vladharbuz3• 11 years ago

If you do this, you are basically doing RPC, so in reality you've given up any RESTfulness.

storea• 11 years ago

I for one like get requests. They are much easier to play with.

jalfresi7• 11 years ago

I'm not sure that a CRUD like interface would be best for something like this. In addition, as this is very much an API and the returned JSON changes depending on the action called on the resource, this looks to me like the ideal candidate to create a custom media type for. With that option open, we can simply define our own request verbs like so:

SHUFFLE /api/deck/<deck-id>

DRAW /api/deck/<deck-id>?count=2

Things become a lot simpler to use, document and implement.

I'd actually take advantage of the custom media-type option and return something much more succinct:

DRAW /api/deck/<deck-id>?count=2

200 OK

8♣

Have the response body be UTF-8 and use the card face runes in the response. Nice and simple.

You dont necessarily have to map your REST API to existing HTTP verbs and media types - in fact the real benefit in a use case like this is that you can implement something appropriate

jalfresi7• 11 years ago

Why the down vote? This is a perfectly acceptable approach! If you're going to down vote at least respond with an argument why

Fogest• 11 years ago

What exactly is hypermedia? Wikipedia is not helping me understand what would not to be changed to make the api use hypermedia?

MarkyC4• 11 years ago

Look up HATEOAS. I find Spring's documentation to be pretty good at explaining: http://spring.io/understanding/HATEOAS

murbard2• 11 years ago

Cute, but an implementation of the mental poker protocol would be far more valuable.

crobertsbmw11• 11 years ago

I think I'll do that next.

listic• 11 years ago

What's it good for, if it doesn't visualize my cards?

brettkc• 11 years ago

Saw something similar demoed at Microsoft's Build event. Looks nice.

Navarr• 11 years ago

There are so many things a good API would have to do...

Different types of decks, handling of a discard, shuffling a card into the deck, shuffling the discard pile into the deck, handling hands, milling a card from the deck, multiple decks acting as one...

Though the simplicity of this api currently just having a deck that you take cards from is neat.

blt• 11 years ago

OP: what was your motivation for this project?

crobertsbmw11• 11 years ago

Thanks for asking. I wanted to build a very simple API, and document it that my year ago self could understand it and actually figure out how to use the whole thing. I don't know if this is a good or bad thing, but I spent more time documenting/designing the single doc page then I did writing the actual API. I also thought the idea was unique enough that it was worth sharing.

The reason for GET and POST is that it was easier for my year ago self to copy and paste a GET url into chrome and hit Enter and see what happens.

spdustin• 11 years ago

Has anyone noticed that it's on Github, and thus it wouldn't be too tough to submit an Issue or, even, a PR?

jessaustin2• 11 years ago

This thread is yet more evidence of the Bikeshed Phenomenon.

Retra• 11 years ago

It's not bike-shedding when there's nothing else to talk about. This is basically a forum about bike shed painting.

joshmn• 11 years ago

And is not exactly encouraging to those who are thinking of submitting their projects.

aarondf• 11 years ago

Hey, you did a thing and told people [0]! Good for you. Is it perfect? No idea, but from reading the comments here a lot of people don't think so. Who cares though [1]! You're so far ahead of so many people because you actually did something.

Next time maybe all your GETs will be RESTful, maybe not. Either way, you've done a thing, put it out there, and are presumably learning a lot by doing so.

Great work.

[0] http://carl.flax.ie/dothingstellpeople.html [1] http://www.garann.com/dev/2013/how-to-blog-about-code-and-gi...

gooseus• 11 years ago

I'm seeing a lot more discussion and debate, rather than criticism.

So good job for that too... I think this Deck of Cards API would make a great case study for analyzing and discussing the varying takes on how a RESTful interface should handle certain situations which aren't as straightforward as the typical blog or todo list examples.

amouat• 11 years ago

A lot of the time it doesn't feel like that to me.

People release things they have worked long and hard on, only to get a bunch of negative comments picking on holes and mistakes.

The weird thing is they are the lucky ones; it's pretty damn hard to make it onto the front-page of HN now, regardless of the quality of the content. (Don't believe me? Take a look at how many times some articles have been reposted and the disparity in number of votes.)

Getting feedback should be great, but not many of us are good at it. Generally, we only comment on things we care about or find interesting (ignoring the stuff that is so bad it deserves harsh criticism like storing passwords in plain-text), but we forget to say that in the comment and only mention the minor flaw we saw.

I don't have a solution to this, other than to tell posters to be prepared for criticism and to take each up-vote as a major token of respect in what you've built.

leovander• 11 years ago

    -people to spam
    -
    -weber@kcnext.com
    -info@cremalab.com
    -andy@lovekc.org
    -info@truckily.com
    -info@secondlifestudios.com
    -help@getflywheel.com
    -hello@elevate.co
    -hello@goodtwin.co
    -Info@ObjectLateral.com
    -editor@siliconprairienews.com
    -info@squareoffs.com
    -josh@socialchangenation.com
    -websupport@psicurity.com
    -sales@rfp365.com
    -travis@rivetcreative.com
    -info@phlyppgear.com
    -kyle@feralfew.com
    -matt@feralfew.com
    -zach@feralfew.com
    -courtney@feralfew.com
    -ben@homesforhackers.com
    -info@cyberjammer.net
    -info@SponsorShout.com

https://github.com/crobertsbmw/deckofcards/commit/2b5675df52...

jaideepsingh• 11 years ago

Kudos! Simple and to the point.

tjbiddle• 11 years ago

Neat! Nice work! Some are definitely criticizing, but hey - you'll always have critics. Unless they're following through with a pull-request, don't mind them.

Great job on putting the project out there!

An idea: Multiple options for deck images - obviously would take time on the artwork, but you could set this in your initial call for a deck (Or maybe even make it so you can change it whenever - if someone would have a need for that for some reason). May be fun.

Great work!

nicobn• 11 years ago

The absence of a pull request does not negate the validity of a criticism. Hacker News is one of the most tech-savvy, intelligent and experienced audience you can find on the web. Everyone sucks, myself included. With that kind of attitude, I would never have learned anything.

Shielding yourself from criticism using an arbitrary criteria only perpetuates ignorance.

Show HN: Deck of Cards – A playing card API

Related Stories