informasjonsforvaltning/example-api

An example API which represents a reference implementation of best practices in The Brønnøysund Register Centre

Example API

An attempt at an reference API-implementation that comply to the following set of requirements:

• user requirements represented as usecases
• a set of quality requirements

The requirements are translated into features (gherkin) in the feature folder.

The features are mapped into an OpenAPI-specification.

Finally, most of the tests are generated from the openAPI-specifcation, while others will be handcoded based on operational features from quality-requirements. Tests are found in the app/test-folder.

The app folder contains an example implementation of an API that should pass all of the tests.

The following diagram illustrates this loosely:

example-api's Issues

Converting the tasks in TODO.md to issues in github

Consider applying HATEOAS to the api

We should explore how to applying HATEOAS to the API. This includes how to represent this in the spec (openAPI) and implement it in code.

Fix errors reported by linter

Inconsistency in example-api

The actual api is about naeringskoder while most of the tests and documentation is still about pets. You need to update tests, specs and documentation.

Convert the openAPI specification to OAS 3.x

Be avare that oatts does not yet support OAS 3.x, ref google/oatts#6

Change model to something more relevant

Instead of using the well known pet-example, change the model to something more relevant to our business, e.g. Organization.

We should probably make a simple model as a subset of https://data.brreg.no/enhetsregisteret/oppslag/underenheter/994667092

Use a linter to validate openAPI spec

Consider e.g. https://github.com/wework/speccy and fit it into the development process.