Deck of Cards AWS API (1.0.0)
Download OpenAPI specification:
Welcome to the Deck of Cards API! 🃏
(NOTE TO FELLOW TECH WRITERS: I intentionally chose a relaxed tone for this documentation to make it more fun and engaging. I'm also able to write in a more formal style.)
This API allows you to create, shuffle, deal, and discard cards from a virtual deck. Every action is secured with JWT authentication, ensuring only authorized users can manage their decks.
Features:
- Create new decks (optionally seeded for reproducibility).
- Deal cards from the deck or the discard pile.
- Peek at the top card of the discard pile.
- Delete decks when you're done playing.
- (Coming soon: Return cards to the discard pile.)
- (Coming soon: Shuffle the discard pile.
This API uses resource-based REST endpoints and JWT authentication.
Admittedly, the only real way this could be used for an actual game is to embed the auth token in a web page or mobile app, potentially exposing it to the public. But let's be realistic; this is just a sample API primarily intended for educational purposes. That and it's just a deck of cards API.
This code was developed by the person who documented it, Jeffrey Cogswell, to demonstrate both how to build an API that runs "serverless" on AWS using:
- Lambda
- API Gateway
- DynamoDB
and how to document code using OpenAPI.
The code is available on github at ... and is licensed for the public domain. Use it however you want!
Use the endpoints below to interact with your decks.
Have fun and play responsibly! 🎲
Coming next (Soon! I promise, since it's not very usable without this feature!)
- Return cards to the discard pile (randomized or in order).
- Shuffle the discard pile.
This documentation (source available via our github) is an example of:
- Using OpenAPI 3.1.0 and writing the documentation right inside the file, so everything is self contained.
- Using Redocly to generate the documentation
Create or log in a user
This call creates or logs in a user. The username and password are required in the body of the request. Upon successful login or user creation, it returns an auth key to be used in the header of future calls. Note that to keep things simple, we're just using a single path for both creating a new user and logging in. If the username already exists, the password must match to log in. If the username doesn't already exist, a new user is created with the username/password.
Request Body schema: application/jsonrequired
| username | string |
| password | string |
Responses
Request samples
- Payload
{- "username": "string",
- "password": "string"
}Response samples
- 200
- 401
{- "authKey": "abcdef123456"
}Create an initialized deck of cards
This call creates a new deck. You can optionally provide a string to seed the random number generator, allowing you to create identical decks by providing the same seed. If you don't provide a seed, a random seed will be used. In both cases, the seed is returned in the response. Note that the seed must be a string of 8 hexadecimal digits (0-9, a-f, A-F). The deck returned will have a unique ID. Use this ID to interact with the deck in future calls. If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
Request Body schema: application/jsonoptional
| seed | string^[0-9a-fA-F]{8}$ A string of 8 hexadecimal digits for seeding the deck. Leave blank for a random deck. |
Responses
Request samples
- Payload
{- "seed": "1a2b3c4d"
}Response samples
- 200
- 401
{- "id": "deck-12345",
- "seed": "random-seed-xyz",
- "deal": [
], - "discard": [
]
}
Get all user decks
Returns a list of the user's deck IDs. Note that this operation does not return entire decks, only the IDs. Use the deck ID to get details of a specific deck (see the next section, "Get details of a specific deck"). If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
Responses
Response samples
- 200
- 401
[- "deck-12345",
- "deck-67890"
]Get details of a specific deck
Retrieves the current state of a specific deck. Returns an object withthe deck's ID, seed, deal pile, and discard pile. Both the deal pile and discard pile consist of card view structures, meaning you can see the id, suit, rank, code, and image of each card. (The image is a URL to the card's image.) The suit is a single letter, either H (Hearts), D (Diamonds), C (Clubs), or S (Spades). The rank is a number or letter, with A, J, Q, K. The code is two characters consisting of the suit and rank (e.g., H3 for the 3 of Hearts). The id is a number from 0 to 51, with the first card in the initial deck being 0 and the last card being 51. (That means the ids change per deck and you cannot use the id to determine the card's rank or suit.) If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
path Parameters
| deckid required | string The unique identifier of the deck. |
Responses
Response samples
- 200
- 401
- 404
{- "id": "deck-12345",
- "seed": "random-seed-xyz",
- "deal": [
], - "discard": [
]
}Delete a deck
Deletes a deck from the system. This action cannot be undone! If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
path Parameters
| deckid required | string The deck ID to delete. |
Responses
Response samples
- 401
"Unauthorized"Deal cards from the deck
Deals one or more cards from the deck. The cards are removed from the deal pile of the deck and returned to the user. If the deal pile is empty, the discard pile is shuffled back into the deal pile (provided the useDiscard query parameter is set to true). If not enough cards are available, as many cards as possible are returned. Note that the returned list of cards is a DeckView object, meaning you can see the id, suit, rank, code, and image of each card. (The image is a URL to the card's image.) If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
path Parameters
| deckid required | string The deck ID from which to deal. |
query Parameters
| count required | integer Default: 1 The number of cards to deal. |
| useDiscard | boolean If true, allows taking cards from the discard pile if needed. |
Responses
Response samples
- 200
- 401
[
]Deal cards from the discard pile
Deals one or more cards from the discard pile. This functions identically to the deal endpoint, but only deals from the discard pile. If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
path Parameters
| deckid required | string The deck ID from which to deal. |
query Parameters
| count | integer Default: 1 The number of cards to deal. |
Responses
Response samples
- 200
- 401
[
]Peek at the top card on the discard pile
Returns the top card of the discard pile. It does not remove the card from the discard pile. If the user is not authorized, the response will be a 401 Unauthorized error.
Authorizations:
path Parameters
| deckid required | string The deck ID. |
Responses
Response samples
- 401
"Unauthorized"