API First Workbench - Process and tools for using API First

API First is a core API design principle used by many companies including Equinor.

With the process and tools in this repo, we provide a structured method of handling the complexity of API First from initial establishment and throughout the lifecycle of the API. This to promote a Test Driven Development (TDD) approach to API development.

Background

This repo was created based on the experience of the Maintenance API team in Equinor implementing the Equinor's API strategy. The repo is open-sourced under Apache 2.0 License.

The goal is to provide value both internally in the company and outside, and hopefully inspire others to contribute and improve upon it.

Features of our workbench

Promote a Test Driven Development (TDD) approach to API development through the following features:

1. Manage and update OpenAPI contract via openapi-editor
2. Verification of OpenAPI contract adherence to standard and best practices through Spectral linting tool
3. Automatically generate developer documentation based on Redoc - See https://equinor.github.io/api-first-workbench/
4. Manage maturing of future releases through release branches with separate developer documentation available for each branch
5. OpenAPI validating proxy for verify implemented API is inline with contract using Prism
6. Code review process through pull requests with automated checks
7. Transform OpenAPI contract automatically to mitigate unsupported features in Azure API Management
8. Support API evolution through deprecation of endpoints and resource properties in OpenAPI contract
9. Issue templates for bug reports and feature requests

Getting started

Itching to get started ? Do the following:

1. Clone this repo
2. Setup github pages to use the gh-pages-source branch
3. Update the api-contract.yaml and commit
4. Wait 1-2 minutes for the Github actions to finish
5. Visit https://<github_account>.github.io/<repo_name>/ for developer documentation

Getting started - Advanced

Here are the next things you want to try out:

1. Create a release branch release/v1.1.0 and update the api-contract.yaml in the branch
2. Wait 1-2 minutes for the Github actions to finish
3. Developer documentation for the release branch will be available at https://<github_account>.github.io/<repo_name>/v1.1.0
4. Deploy the OpenAPI proxy validator using the Dockerfile openapi-proxy-validator/openapi_proxy_validator.Dockerfile.
   This is dependent on the file openapi-contract/generated/api-contract-flattened.yaml generated by Github action openapi_prepare_for_prism.yml.
   For Equinor usage, setup an app using Radix instead. This will rely on the file radixconfig.yaml in the root of the repo. Note: openapi-proxy-validator/openapi_proxy_validator.Dockerfile expects https://api-dev.gateway.equinor.com is the location of the actual API (so update accordingly if this's not the case)
5. Create API tests, for example in Postman, with the OpenAPI proxy validator as the endpoint. Inspect the sl-violations response header for errors. For Postman, postman_collection_test_script.js can be used for converting sl-violations into failed postman tests for all endpoints in the collection.
6. Add additional linting rules in openapi-linter/.spectral.yml based on Spectral documentation
7. Perform code review and merge to main by pull request of release/v1.1.0 towards main.
8. If using Azure API Management, use openapi-contract\generated\api-contract-azure-apim-compatible.yaml to create the API definition there

More about API First

API First has two key elements:

• Define the API using a standard specification language before any line of code is written
• Get feedback on the API definition from team members and client developers

With the API first approach, we can achieve:

• Evolving the API and learn about it’s usage in an efficient matter, without having to write any code
• Decoupling of API design and development. The API definition becomes a contract that teams can work on without having to wait for the implementation to be completed. And the implementation can be changed / replaced without impacting the clients.
• Specifying APIs with a standard specification language facilitates usage of tools for generating documentation, mock code, automatic quality checks, API Management tools, etc.

Process

Mature

Implement with Test Driven Development

Release to production