pokeapi Documentation

File: README.md Copy Chapter

A RESTful API for Pokémon - pokeapi.co

Beta GraphQL support is rolling out! Check out the GraphQL paragraph for more info.

Table of Contents Copy Chapter

• Setup
• Database setup
• Docker and Compose
• GraphQL
• Kubernetes
• Wrappers
• Donations
• Contributing

Setup   [](https://www.python.org/downloads/release/python-3137/) Copy Chapter

• Download this source code into a working directory, be sure to use the flag --recurse-submodules to clone also our submodules.

• Install uv for Python environment management.

• Install the requirements using the Makefile commands:

  sh Copy

  make install
  # This will install all the required packages and libraries for using PokeAPI

• Install the pre-commit hooks using the Makefile commands (optional but recommended):

  sh Copy

  make pre-commit-install

  [!NOTE]
  Pre-commit hooks are optional but recommended for maintaining code quality and consistency. If you do not want it to automatically run on every commit, you can run it manually with make pre-commit before commiting and pushing your changes.

• Lint, format, and typecheck your code changes:

  sh Copy

  make lint-check   # or: uv run ruff check .
  make format       # or: uv run ruff format .
  make typecheck    # or: uv run ty check

[!NOTE]
As of right now we are not strictly enforcing linting and typechecking, but we will be in the future. Please try to make sure your code passes these checks.

• Set up the local development environment using the following command:

  sh Copy

  make setup

• Run the server on port 8000 using the following command:

  sh Copy

  make serve

Database setup Copy Chapter

To build or rebuild the database by applying any CSV file update, run

make build-db

Visit localhost:8000/api/v2/ to see the running API!

Each time the build-db script is run, it will iterate over each table in the database, wipe it, and rewrite each row using the data found in data/v2/csv.

If you ever need to wipe the database use this command:

make wipe-sqlite-db

If the database schema has changed, generate any outstanding migrations and apply them

make make-migrations
make migrate

Run make help to see all tasks.

Docker and Compose   [](https://hub.docker.com/r/pokeapi/pokeapi) Copy Chapter

There is also a multi-container setup, managed by Docker Compose V2. This setup allows you to deploy a production-like environment, with separate containers for each service, and is recommended if you need to simply spin up PokéAPI.

Start everything by

make docker-setup

If you don't have make on your machine you can use the following commands

docker compose up -d
docker compose exec -T app python manage.py migrate --settings=config.docker_compose
docker compose exec -T app sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker_compose'

Browse localhost/api/v2/ or localhost/api/v2/pokemon/bulbasaur/ on port 80.

To rebuild the database and apply any CSV file updates, run

make docker-build-db

If the database schema has changed, generate the migrations and apply those

make docker-make-migrations
make docker-migrate

GraphQL   [](https://github.com/hasura/graphql-engine) Copy Chapter

When you start PokéAPI with the above Docker Compose setup, an Hasura Engine server is started as well. It's possible to track all the PokeAPI tables and foreign keys by simply

# hasura cli needs to be installed and available in your $PATH: https://hasura.io/docs/2.0/hasura-cli/install-hasura-cli
# hasura cli's version has to greater than v2.48.1
make hasura-apply

When finished browse http://localhost:8080 and you will find the admin console. The GraphQL endpoint will be hosted at http://localhost:8080/v1/graphql.

A free public GraphiQL console is browsable at the address https://beta.pokeapi.co/graphql/console/. The relative GraphQL endpoint is accessible at https://beta.pokeapi.co/graphql/v1beta

A set of examples is provided in the directory /graphql/examples of this repository.

Kubernetes   [](https://github.com/PokeAPI/pokeapi/actions/workflows/docker-k8s.yml) Copy Chapter

Kustomize files are provided in the folder https://github.com/PokeAPI/pokeapi/tree/master/Resources/k8s/kustomize/base/. Create and change your secrets:

cp Resources/k8s/kustomize/base/secrets/postgres.env.sample Resources/k8s/kustomize/base/secrets/postgres.env
cp Resources/k8s/kustomize/base/secrets/graphql.env.sample Resources/k8s/kustomize/base/secrets/graphql.env
cp Resources/k8s/kustomize/base/config/pokeapi.env.sample Resources/k8s/kustomize/base/config/pokeapi.env
# Edit the newly created files

Configure kubectl to point to a cluster and then run the following commands to start a PokéAPI service.

kubectl apply -k Resources/k8s/kustomize/base/
kubectl config set-context --current --namespace pokeapi # (Optional) Set pokeapi ns as the working ns
# Wait for the cluster to spin up
kubectl exec --namespace pokeapi deployment/pokeapi -- python manage.py migrate --settings=config.docker_compose # Migrate the DB
kubectl exec --namespace pokeapi deployment/pokeapi -- sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker_compose' # Build the db
kubectl wait --namespace pokeapi --timeout=120s --for=condition=complete job/load-graphql # Wait for Graphql configuration job to finish

This k8s setup creates all k8s resources inside the Namespace pokeapi, run kubectl delete namespace pokeapi to delete them. It also creates a Service of type LoadBalancer which is exposed on port 80 and 443. Data is persisted on 12Gi of ReadWriteOnce volumes.

Wrappers Copy Chapter

Donations Copy Chapter

Help to keep PokéAPI running! If you're using PokéAPI as a teaching resource or for a project, consider sending us a donation to help keep the service up. We get 1+ billion requests a month!

Thank you to all our backers! Become a backer

Join Us On Discord! Copy Chapter

We have a Discord server. It is a simple place where people can chat with each other in a respecful manner. Not all maintainers/code contributors are signed up and your question might not be answered. Consider opening an issue if you want more visibility or you want to talk to the maintainers. Be excellent to each other :smile:

Contributing Copy Chapter

This project exists thanks to all the people who contribute

All contributions are welcome: bug fixes, data contributions, and recommendations.

Please see the issues on GitHub before you submit a pull request or raise an issue, someone else might have beat you to it.

To contribute to this repository:

• Fork the project to your own GitHub profile

• Download the forked project using git clone:

  sh Copy

  git clone --recurse-submodules [email protected]:<YOUR_USERNAME>/pokeapi.git

• Create a new branch with a descriptive name:

  sh Copy

  git checkout -b my_new_branch

• Write some code, fix something, and add a test to prove that it works. No pull request will be accepted without tests passing, or without new tests if new features are added.

• Commit your code and push it to GitHub

• Open a new pull request and describe the changes you have made.

• We'll accept your changes after review.

Simple!

File: graphql/v1beta2/examples/go/README.md Copy Chapter

Go examples

`pokemon.go` Copy Chapter

Fetches details about a Pokémon and prints an unformatted JSON to the stdout. The name of the Pokémon is passed as a variable.

go run pokemon.go # | jq

File: graphql/v1beta2/examples/node/README.md Copy Chapter

Node examples

`pokemon.js` Copy Chapter

Fetches info about Staryu using node-fetch.

npm i
node pokemon.js

File: graphql/v1beta2/examples/README.md Copy Chapter

GraphQL examples

You can use all the .gql examples in our console at https://beta.pokeapi.co/graphql/console/.

Inside the folders you find GraphQL queries implemented in different languages, frameworks and libraries.

File: graphql/v1beta/examples/go/README.md Copy Chapter

Go examples

`pokemon.go` Copy Chapter

Fetches details about a Pokémon and prints an unformatted JSON to the stdout. The name of the Pokémon is passed as a variable.

go run pokemon.go # | jq

File: graphql/v1beta/examples/node/README.md Copy Chapter

Node examples

`pokemon.js` Copy Chapter

Fetches info about Staryu using node-fetch.

npm i
node pokemon.js

File: graphql/v1beta/examples/README.md Copy Chapter

GraphQL examples

You can use all the .gql examples in our console at https://beta.pokeapi.co/graphql/console/.

Inside the folders you find GraphQL queries implemented in different languages, frameworks and libraries.

File: Resources/docker/app/README.md Copy Chapter

Quick reference

• Maintained by:
  the PokeAPI Contributors

• Where to get help:
  PokeAPI Slack.

• Where to file issues:
  https://github.com/PokeAPI/pokeapi/issues

• Source of this description:
  pokeapi repo's Resources/docker/app/ directory

Supported tags and respective `Dockerfile` links Copy Chapter

• master
• staging

pokeapi uses python:3.14-alpine as base image.

What is PokeAPI? Copy Chapter

PokeAPI is a full RESTful API linked to an extensive database detailing everything about the Pokémon main game series.

pokeapi.co

How to use this image Copy Chapter

This container connects to a Postgres database via the environment variables POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_PORT.

The container connects to a Redis cache via the environment variable REDIS_CONNECTION_STRING.

Run the container Copy Section

The container exposes port 80. It needs a PostgreSQL and a Redis instance to connect to. Refer to the section How to use this image for mapping the environment variables.

It's recommended to use the provided docker-compose.yml to start a container from this image.

Build the data Copy Section

Pokémon data isn't automatically present in this image. All Pokémon data is persisted in a PostgreSQL database and thus needs to be built.

When the container is up and running, run the following shell commands:

docker exec pokeapi python manage.py migrate --settings=config.docker_compose
docker exec pokeapi sh -c 'echo "from data.v2.build import build_all; build_all()" | python manage.py shell --settings=config.docker_compose'