🃏 Decks, Cards, and Games (♠️, ♦️, ♣️, ♥️)

This repository hosts a backend API designed for card games, built using Golang and the Gin web framework.

API Overview

The API supports the following functionalities:

• Create a Deck: Generates a deck of cards. By default, a deck contains 52 cards (13 from each suit: Spades, Diamonds, Clubs, Hearts, in order). Users can specify a subset of cards to include in the deck. The API also supports shuffling the deck.

{
  "deck_id": "a251071b-662f-44b6-ba11-e24863039c59",
  "shuffled": false,
  "remaining": 30
}

---

• Open a Deck: Retrieves details about a specific deck, including its ID, shuffle status, remaining cards, and the cards themselves.

{
  "deck_id": "a251071b-662f-44b6-ba11-e24863039c59",
  "shuffled": false,
  "remaining": 3,
  "cards": [
    {"value": "ACE", "suit": "SPADES", "code": "AS"},
    {"value": "KING", "suit": "HEARTS", "code": "KH"},
    {"value": "8", "suit": "CLUBS", "code": "8C"}
  ]
}

---

• Draw Cards: Allows drawing a specified number of cards from a deck.

{
  "cards": [
    {"value": "QUEEN", "suit": "HEARTS", "code": "QH"},
    {"value": "4", "suit": "DIAMONDS", "code": "4D"}
  ]
}

Getting Started

Prerequisites

• Ensure you have Go installed on your machine (preferably 1.20+).
• Clone this repository and navigate into the project directory.

Build the API

Compile the application: go build ./...

Run the API

Start the API server: go run main.go

Testing the API

You can test the API by running automated tests by: go test ./...

There is also a Postman Collection

List of APIs

Sharing list of APIs here:

Creating Decks

1. (Generating a full deck of unshuffled cards) curl -X POST "http://localhost:8080/api/v1/decks"
2. (Generating a full deck of shuffled cards) curl -X POST "http://localhost:8080/api/v1/decks?shuffle=true"
3. (Generating a partial deck of unshuffled cards) curl -X POST "http://localhost:8080/api/v1/decks?shuffle=false&cards=AS,2C,KH,KD,TC"
4. (Generating a partial deck of shuffled cards) curl -X POST "http://localhost:8080/api/v1/decks?shuffle=true&cards=AS,2C,KH,KD,TC"

Opening Decks

1. (Opening a deck of cards) curl -X GET "http://localhost:8080/api/v1/decks/XXXXXXXX-4e84-4dc6-968c-XXXXXXXX"

Drawing Cards

1. (Drawing cards from a deck) curl -X POST "http://localhost:8080/api/v1/decks/XXXXXXXX-4e84-4dc6-968c-XXXXXXXX/draw?count=3

Known Issues

Maintaining a list of items here that can be worked on and improved.

1. Is there a better way to handle the number 10 since it's the only double-digit? 🤔

Support

For questions or feedback, please contact me at tayyab.abdussami@gmail.com.

Thank you for checking out my project! This is my second project in Go, and I'm eager to continue learning and improving.