Last updated

API Governance

The standards you adopt for your API speak volumes about your API identity to its users. Take our quiz, work out what matters to you and to your users - and then download a ready-made configuration file so you can start checking your API straight away.

Workshop for API standards

Bring together the API stakeholders in your organization and harness their perspectives and experience to build a set of API standards that fits your situation. We recommend a 90 minute time slot; meet in person if you can, or switch to full remote so everyone has their own place in the virtual call.

During the session

  • For each question, look for quick consensus in the group. Many of these questions will merely formalize your existing API practices and won't need much discussion.
  • For anything more contentious, set a 5 minute timer and ensure everyone in the group has the opportunity to put their point of view.
  • All questions have an option that doesn't add anything to your rule set - use this for topics where agreement can't be reached, or where there is no strong view.
Start small

We always say "Start small". When adding API linting to your process, adding it with one rule is more valuable than you think. Once the linting process is implemented, you and your team can iterate towards your ideal standards.

Written standards

  • Make a note of anything that isn't exactly covered by the quiz, so you can expand your ruleset later. This is just to get you started.
  • Also note any other conventions or API practices that the group agrees should be followed. Add them to a written standards document even if they can't be automatically checked. These can be used by humans at API review time.


If you can, invite someone in to the group as the facilitator, so that all stakeholders can participate fully in the discussions.

Refreshments can also help the process 😉

Should the main title include "API" or omit it because "API" is redundant?
  - recommended
rules: {}

Using API standards in practice

After taking the quiz above, you can download a Redocly configuration file that can check any OpenAPI file against the options that you selected.

  1. Download the redocly.yaml file from the quiz.

  2. Install Redocly CLI if you don't have it already.

  3. Run Redocly CLI from the directory where you stored redocly.yaml, and give the path to your OpenAPI file (or copy that locally too). The command will be something like this:

    redocly lint openapi.yaml
  4. Check the output to see how your API conforms to the standards.

  5. Learn more about API standards and check the full list of rules to develop your API governance practice further.