5e-srd-api

repository·main·Indexed 20 days ago

https://github.com/5e-bits/5e-srd-api

A REST API providing programmatic access to D&D 5th Edition System Reference Document (SRD) data, including monsters, spells, and classes. The API supports version /api/2014 and provides OpenAPI specifications, Postman collections, and a GraphQL schema for the 2014 edition. It can be deployed locally using Docker Compose with MongoDB and Redis.

Tokens
11.2K
Snippets
30
Records
56
Agent score
70%

What's inside 5e-srd-api

  1. Explore the OpenAPI file organization

    main

    The OpenAPI definition is modularized to improve reusability and readability. The root definition is located in swagger.yml. The documentation is split into three main directories:

    • /schemas: Contains .yml files defining SchemaObject types, which correspond to models in src/models. These describe response body structures.
    • /paths: Contains .yml files defining PathItemObject operations, corresponding to controllers in src/controllers/api. These include example responses.
    • /parameters: Contains reusable path and query parameter definitions.

    Each directory includes a combined.yml file containing named references to all objects in that directory. To avoid circular references, always reference objects via these combined.yml files.

  2. Run the 5e-srd-api locally with Docker

    main

    To run the API locally, you must first ensure you have the latest version of the database image, then build and start the services using Docker Compose.

    Standard Setup (AMD64):

    1. Pull the latest database image:
      docker compose pull
    2. Build and start the API:
      docker compose up --build

    Apple Silicon (M1/M2/M3 Macs): The default image on ghcr.io targets amd64. For Apple Silicon, you must build the database image locally from the 5e-database repository:

    1. Clone the database repository into the parent directory:
      cd ../
      git clone https://github.com/5e-bits/5e-database.git
    2. Modify the docker-compose.yml file in the 5e-srd-api directory. Replace the line image: bagelbits/5e-database with build: ../5e-database (or the path to your local database clone).
    3. Run docker compose up --build as usual.
    docker compose pull
    docker compose up --build
  3. Mock S3 image resources for local testing

    main

    The API uses an S3 bucket named dnd-5e-api-images (under the /monsters folder) to store monster images. To test image requests locally, you can use localstack to mock S3.

    Setup Steps:

    1. Install localstack, awscli, and awslocal.
    2. Configure and start the localstack container:
      export AWS_CONFIG_ENV=localstack_dev
      localstack start
      awslocal s3api create-bucket --bucket dnd-5e-api-images
      awslocal s3 cp aboleth.png s3://dnd-5e-api-images/monsters/
      npm run dev
    3. Verify by requesting an image via curl or a browser:
      curl http://localhost:3000/api/2014/monsters/aboleth.png --output downloaded-aboleth.png
    export AWS_CONFIG_ENV=localstack_dev
    localstack start
    awslocal s3api create-bucket --bucket dnd-5e-api-images
    awslocal s3 cp aboleth.png s3://dnd-5e-api-images/monsters/
    npm run dev
  4. Generate a Postman collection from OpenAPI

    main

    You can generate a Postman collection based on the OpenAPI definition using the npm run gen-postman task. This task uses portman and the configuration in portman-cli.json to create the collection. Once generated, you can import the resulting file into Postman for testing and exploration.

    Alternatively, you can run portman directly from the command line. For example, to generate a collection from the bundled OpenAPI file:

    portman -l src/swagger/dist/openapi.yml -o collection.postman.json -t
    npm run gen-postman
  5. Make API requests to the 5e-srd-api

    main

    The API is accessed via a root address. Currently, the API is versioned by the release year of the SRD. The primary available version is /api/2014.

    Base URL: http://localhost:3000/api/2014 (for local development).

    Available Endpoints (v2014):

    • /api/2014/ability-scores
    • /api/2014/classes
    • /api/2014/conditions
    • /api/2014/damage-types
    • /api/2014/equipment-categories
    • /api/2014/equipment
    • /api/2014/features
    • /api/2014/languages
    • /api/2014/magic-schools
    • /api/2014/monsters
    • /api/2014/proficiencies
    • /api/2014/races
    • /api/2014/skills
    • /api/2014/spells
    • /api/2014/subclasses
    • /api/2014/subraces
    • /api/2014/traits
    • /api/2014/weapon-properties

    Note: /api/2024 is planned for a future release.

    http://localhost:3000/api/2014
  6. Understand the MultipleItemUnion2024 GraphQL union type

    main

    In the 2024 edition of the API, equipment options that provide multiple items use the MultipleItemUnion2024 union type. When querying an equipment option of type multiple, the items field will return an array of objects that can be one of the following three types:

    1. CountedReferenceOption2024: A specific quantity of a single piece of equipment (e.g., "2 torches").
    2. MoneyOption2024: A specific amount of currency (e.g., "50 gp").
    3. ChoiceItemOption2024: A choice from a specific equipment category (e.g., "choose 2 items from the Explorer's Pack category").

    To distinguish between these in a GraphQL query, use an inline fragment (... on TypeName) and check the option_type field.

    query {
      # Example of how to query the union
      equipmentOption {
        items {
          __typename
          ... on CountedReferenceOption2024 {
            option_type
            count
            of {
              name
            }
          }
          ... on MoneyOption2024 {
            option_type
            count
            unit
          }
          ... on ChoiceItemOption2024 {
            option_type
            choice {
              choose
              from {
                equipment_category {
                  name
                }
              }
            }
          }
        }
      }
    }
  7. Understand Choice and Option structures

    main

    The API uses a hierarchical structure to represent decision-making mechanics (e.g., 'Choose one of the following options').

    1. Choice: The top-level object describing the decision. It includes a description (desc), the number of items to select (choose), a type, and a source from (an OptionSet).
    2. OptionSet: Defines the collection of available choices. It can be one of three types:
      • equipment_category: References an equipment category via equipment_category (APIReference).
      • resource_list: Points to an external resource via resource_list_url (string).
      • options_array: Contains a direct list of Option objects.
    3. Option: The individual items within a set. Options are highly specialized (e.g., ActionOption, DamageOption, MoneyOption) to provide specific data like damage dice, ability scores, or currency units.
  8. Understand 2024 Monster Damage Choice types

    main

    The 2024 edition of the API uses specific GraphQL types to handle monster actions that require a choice of damage.

    • DamageChoice2024: Represents the top-level choice, containing a choose integer, a type, a from object (the set of options), and an optional desc.
    • DamageChoiceOptionSet2024: A collection of options identified by option_set_type.
    • DamageChoiceOption2024: A single damage option within a set, containing an option_type and a damage object.
    • DamageOrDamageChoice2024Union: A union type that allows a field to return either a standard Damage object or a DamageChoice2024 object.
  9. Understand 2024 Monster Breath Choice types

    main

    For monsters with breath weapons, the 2024 API provides structured breath choices:

    • BreathChoice2024: The main choice object containing choose, type, from, and an optional desc.
    • BreathChoiceOptionSet2024: A set of options identified by option_set_type.
    • BreathChoiceOption2024: A specific breath option containing option_type, name, dc (Difficulty Class), and an optional array of damage objects.
  10. Understand the BaseOrderInterface for sorting

    main

    Sorting in the API is handled via a recursive interface called BaseOrderInterface. This allows for multi-level sorting (e.g., sort by name, then by date).

    • by: The field name to sort by.
    • direction: The direction of the sort using OrderByDirection (e.g., ASC or DESC).
    • then_by: (Optional) An instance of BaseOrderInterface to define the next level of sorting if the previous field results in a tie.
  11. Understand 2024 Monster Action Choice types

    main

    Monster actions in the 2024 edition can involve complex choices via the following types:

    • ActionChoice2024: The top-level choice object containing choose, type, from, and an optional desc.
    • ActionChoiceOptionSet2024: A set of options identified by option_set_type.
    • ActionOption2024Union: A union type that can return either a single ActionChoiceOption2024 or a MultipleActionChoiceOption2024.
    • ActionChoiceOption2024: A single action option containing option_type, action_name, count, type, and optional notes.
    • MultipleActionChoiceOption2024: A grouping of multiple action options, identified by option_type and containing an items array of ActionChoiceOption2024.