{"id":13602174,"url":"https://github.com/otto-de/api-guidelines","last_synced_at":"2025-11-06T23:03:39.503Z","repository":{"id":160837116,"uuid":"606045024","full_name":"otto-de/api-guidelines","owner":"otto-de","description":"A set of rules to build consistent and high quality REST and Async APIs at OTTO.","archived":false,"fork":false,"pushed_at":"2025-08-04T06:39:34.000Z","size":7778,"stargazers_count":49,"open_issues_count":23,"forks_count":16,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-08-04T09:43:10.101Z","etag":null,"topics":["api","apidesign","async","events","guidelines","otto","rest-api","restapi","restful"],"latest_commit_sha":null,"homepage":"https://api.otto.de/portal/guidelines","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/otto-de.png","metadata":{"files":{"readme":"README.md","changelog":"changes/changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-24T13:27:51.000Z","updated_at":"2025-08-04T06:39:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"8375547d-3187-40eb-8e7c-ae807dd3edb7","html_url":"https://github.com/otto-de/api-guidelines","commit_stats":{"total_commits":2342,"total_committers":51,"mean_commits":45.92156862745098,"dds":0.5303159692570453,"last_synced_commit":"15c925dedcb3d474b17d33fc35fc6015f5289c2c"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/otto-de/api-guidelines","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otto-de%2Fapi-guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otto-de%2Fapi-guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otto-de%2Fapi-guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otto-de%2Fapi-guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/otto-de","download_url":"https://codeload.github.com/otto-de/api-guidelines/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otto-de%2Fapi-guidelines/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283095890,"owners_count":26778518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-06T02:00:06.180Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","apidesign","async","events","guidelines","otto","rest-api","restapi","restful"],"created_at":"2024-08-01T18:01:15.712Z","updated_at":"2025-11-06T23:03:39.487Z","avatar_url":"https://github.com/otto-de.png","language":"TypeScript","readme":"# OTTO API Guidelines\n\nWith these guidelines, we aim to establish a set of best practices and standards for designing, developing, documenting, and maintaining APIs.\n\nSkip to:\n\n- [Purpose](#purpose)\n- [How to read the guidelines](#how-to-read-the-guidelines)\n- [API linting](#api-linting)\n  - [Installation](#installation)\n  - [Recommended Redocly configuration](#recommended-redocly-configuration)\n  - [Lint your specs](#lint-your-specs)\n  - [Change severity](#change-severity)\n- [Attribution](#attribution)\n\n## Purpose\n\nWe consider API guidelines essential to ensure that our APIs are consistent, reliable, secure, and easy to use.\n\nOur APIs are a valuable part of our business assets, as with APIs we generate the corresponding operating values.\nIdeally, by applying the API guidelines, all APIs look as if they were created by a single team, thus providing API consumers with a homogeneous, easy-to-use product.\nThis facilitates a great developer experience and the ability to quickly compose complex business processes.\nWith this in mind, we trust that our teams build APIs that are:\n\n- self-explanatory\n- easy to use and robust\n- of high quality\n- consistent\n- transparently versioned\n- RESTful with respect to REST APIs.\n\n## How to read the guidelines\n\nThese guidelines include rules for REST and asynchronous APIs and are supplemented by rules applicable to both types of APIs.\nIt is a living document and will be revised over time as new rules are added or existing rules are modified.\n\nThe guidelines are structured into individual rules that use the key words “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY”.\nThese keywords are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt).\nIn this document, such keywords are highlighted at the beginning of each section in uppercase letters and are color-coded.\n\n\u003e **_Disclaimer:_**  Code examples may be incomplete and/or may violate the rules described in the guidelines. Examples are intentionally kept simple to make them more accessible and easier to comprehend. They are always correct in their context, but not necessarily outside of it. Common examples for this are omitted headers such as Authorization or omitted (mandatory) properties in JSON responses.\n\n## API linting\n\nOur APIs can be validated using the [Redocly CLI toolbox](https://github.com/Redocly/redocly-cli).\nBy automating the verification of APIs againgst our guidelines, we enable our developers to get a much quicker view of where API design needs to be adjusted.\nIf you'd like to use it for your own APIs, this is what you need to do:\n\n### Installation\n\n1. [Install Redocly CLI](https://redocly.com/docs/cli/installation/).\n2. Add the following code snippet to your existing `.npmrc` or create a `.npmrc`. Set a valid GITHUB_TOKEN. (Sadly this necessary even if packages are public, we hope publishing packages to https://www.npmjs.com later to avoid this step)\n\n   ```text\n   @otto-de:registry=https://npm.pkg.github.com/\n   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n   ```\n\n3. Install the dependency.\n\n   ```shell\n   npm install -D @otto-de/api-guidelines\n   ```\n\n4. Add the following code snippet to your redocly configuration:\n\n   ```yaml\n   extends:\n     - api-guidelines/recommended\n\n   plugins:\n     - ./node_modules/@otto-de/api-guidelines/dist/plugin.cjs\n   ```\n\n### Recommended Redocly configuration\n\n```yaml\nextends:\n  - recommended\n  - api-guidelines/recommended\n\nplugins:\n  - ./node_modules/@otto-de/api-guidelines/dist/plugin.cjs\n```\n\n### Lint your specs\n\n```shell\nredocly lint ./path/to/your/spec.yml\n```\n\n### Change severity\n\nIf you'd like to disable or change the severity of a specific rule,\nyou can add this to your Redocly configuration, for example, like this:\n\n```yaml\nrules:\n  api-guidelines/always-return-json-object: off\n  api-guidelines/define-permissions-with-scope: warn\n```\n\n## Attribution\n\nAt this point we would like to send Kudos to Zalando SE whose Tech Team did a great job crafting the [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/#).\nAs much of the content resonates with what we do at OTTO, their well-prepared document inspired us and in certain parts provided a basis when crafting the OTTO API Guidelines.\n\nThe Zalando RESTful API Guidelines are published under the [Creative Commons Attribution 4.0 International License](https://github.com/zalando/restful-api-guidelines/blob/main/LICENSE) (CC BY 4.0).\nFor further notes on these OTTO API Guidelines’ license under CC BY 4.0, please refer to the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode).\n\n","funding_links":[],"categories":["api"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotto-de%2Fapi-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fotto-de%2Fapi-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotto-de%2Fapi-guidelines/lists"}