18 Automating API design guidelines
- Detecting API design problems or improvements with a program
- Deciding what to check in API designs
- Typical elements to target and checks to perform
- Returning helpful feedback
- Using and tweaking shared automated guidelines
Our API design guidelines indicate that all property names should be in camel case. However, it’s common to make typos (using Account instead of account) or be unsure about camel-case acronyms (sourceIBAN or sourceIban). We also may forget to add pagination to a search operation or be uncertain about the exact names of the pagination query parameters (cursor versus next and pageSize versus limit) and whether they are required or optional.
18.1 What API linting is and how it can help us
18.1.1 Detecting API design and OpenAPI authoring problems
18.1.2 Applying guidelines seamlessly and concentrating on user needs
18.2 Using an API linter to automate API design guidelines
18.2.1 Developing linting rules to automate guidelines
18.2.2 Using our automated guidelines while designing APIs
18.2.3 Choosing an API linter
18.3 Introducing Spectral
18.3.1 Linting an OpenAPI document with Spectral CLI
18.3.2 How Spectral lints an OpenAPI document
18.3.3 Editing Spectral rulesets
18.4 Deciding what API linting rules verify
18.4.1 Using our guidelines to create only needed rules
18.4.2 Finding small problems to solve
18.4.3 Simplifying rules with shared OpenAPI components
18.4.4 Ensuring appropriate granularity with a concise name and description
18.5 Targeting elements to check in the OpenAPI documents
18.5.1 Starting rule development by targeting the proper elements
18.5.2 Targeting any element in the OpenAPI document
18.5.3 Dealing with references to local or shared components
18.5.4 Creating a library to target typical elements
18.6 Checking element values
