serlo.org – API

Unified GraphQL API for Serlo.

Setup

You need:

• Node.js and yarn cli from .tool-versions installed on your system.
  • You may use asdf for the installation.
• Docker

Now follow the upcoming instructions.

Clone

# Clone the project:
$ git clone https://github.com/serlo/api.serlo.org.git
$ cd api.serlo.org

Development

Initial setup

Run yarn to install the dependencies of all packages.

Start

Make sure Docker is running and then run yarn start to start Redis.

Setup NODE_OPTIONS

If in the /etc/hosts file of your host you have the ::1 (IPv6) mapped to localhost, you will additionally need to set: --dns-result-order=ipv4first in the NODE_OPTIONS environment variable:

export NODE_OPTIONS=--dns-result-order=ipv4first

Caching

By default, while developing, the caching won't work. If you want to have caching, change the value CACHE_TYPE in .env to any other value besides 'empty'.

Run tests

• yarn test runs the unit tests (requires yarn start:redis beforehand)
• yarn pacts runs the contract tests (requires yarn start:redis beforehand)
• yarn check:all runs all checks (like the linter and tests) to check whether your codebase is ready to be merged into main

Run specific test

You can pass the name of your test as an argument. For example to only run the tests of the metadata.

yarn test -- metadata

Use the GraphQL playground

After yarn start, you can open the GraphQL playground via http://localhost:3000/___graphql. Note that most queries will need a running serlo/serlo.org-database-layer dev environment.

If you need to run requests authenticated/authorized, use yarn auth to be authenticated as user with id 1 or yarn auth <id> to choose a specific user.

Happy coding!

Stop

Interrupt the yarn start command to stop the dev server and run yarn stop:redis to stop Redis.

Automatically check your codebase before pushing

You can use git hooks to automatically check the whole codebase before you push to the server. To configure it, run the following commands in the root directory:

echo "yarn check:all --no-uncommitted-changes" > .git/hooks/pre-push
chmod +x .git/hooks/pre-push

With git push --no-verify you can bypass the automatic checks.

Repository structure

• __fixtures__ contains test data (used by both unit and contract tests).
• __tests__ contains the unit tests.
• __tests-pacts__ contains the contract test.
• src/internals contains a couple of internal data structures. In most cases, you won't need to touch this. Here we hide complexity that isn't needed for typical development tasks.
• src/model defines the model.
• src/schema defines the GraphQL schema.

We have ~ as an absolute path alias for ./src in place, e.g. ~/internals refers to ./src/internals.

Other commands

• yarn build:server builds the server (only needed for deployment)
• yarn changelog generates the changelog (only needed for deployment)
• yarn deploy:images deploys the docker images to our Container Registry (only needed for deployment)
• yarn format formats all source code
• yarn lint lints all source code
• yarn license updates license headers in source files
• yarn pacts runs the contract tests
• yarn test runs the unit tests
• yarn codegen generates TypeScript types from GraphQL schema
• yarn start spins up the development environment
• yarn update-version starts the process for adding a new version (only needed for deployment)