DisplayApi

OpenAPI specification

The OpenAPI specification is committed to this repo as public/api-spec-v1.yaml and as public/api-spec-v1.json.

A CI check will compare the current API implementation to the spec. If they are different the check will fail.

If a PR makes planned changes to the spec, the commited file must be updated:

docker compose exec phpfpm composer update-api-spec

If these are breaking changes the API version must be changed accordingly.

Stateless

The API is stateless except /v1/authentication routes. Make sure to set the CORS_ALLOW_ORIGIN correctly in .env.local.

Development Setup

A docker-compose.yml file with a PHP 8.0 image is included in this project. To install the dependencies you can run

docker compose up -d
docker compose exec phpfpm composer install

# Run migrations
docker compose exec phpfpm bin/console doctrine:migrations:migrate

JWT Auth

To authenticate against the API locally you must generate a private/public key pair:

docker compose exec phpfpm bin/console lexik:jwt:generate-keypair

Then create a local test user if needed:

docker compose exec phpfpm bin/console app:user:add

You can now obtain a token by sending a POST request to the /authentication/token endpoint:

curl -X 'POST' \
  'http://displayapiservice.local.itkdev.dk/authentication/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "test@test.com",
  "password": "testtest"
}'

Either on the command line or through the OpenApi docs at /docs

You can use the token either by clicking "Authorize" in the docs and entering

Bearer <token>

as the api key value. Or by adding an auth header to your requests

curl -X 'GET' \
  'http://displayapiservice.local.itkdev.dk/v1/layouts?page=1&itemsPerPage=10' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer <token>'

Psalm static analysis

Psalm is used for static analysis. To run psalm do

docker compose exec phpfpm composer install
docker compose exec phpfpm ./vendor/bin/psalm

Psalm error level is set to level 2.

Composer normalizer

Composer normalize is used for formatting composer.json

docker compose exec phpfpm composer normalize

Check Coding Standard

The following command let you test that the code follows the coding standard for the project.

PHP files PHP Coding Standards Fixer

docker compose exec phpfpm composer coding-standards-check

Markdown files (markdownlint standard rules)

docker run -v ${PWD}:/app itkdev/yarn:latest install
docker run -v ${PWD}:/app itkdev/yarn:latest check-coding-standards

Apply Coding Standards

To attempt to automatically fix coding style issues