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

# Load fixtures (Optional)
docker compose exec phpfpm bin/console hautelook:fixtures:load --no-interaction

The fixtures have an admin user: [email protected] with the password: apassword The fixtures have an editor user: [email protected] with the password: apassword The fixtures have the image-text template, and two screen layouts: full screen and "two boxes".

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": "[email protected]",
  "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

• PHP files PHP Coding Standards Fixer

  docker compose exec phpfpm composer coding-standards-apply

• Markdown files (markdownlint standard rules)

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

CI

Github Actions are used to run the test suite and code style checks on all PRs.

If you wish to test against the jobs locally you can install act. Then do:

act -P ubuntu-latest=shivammathur/node:latest pull_request

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.