The API linter provides real-time checks for compliance with many of the API standards, documented using API Enhancement Proposals. It operates on API surfaces defined in protocol buffers.
For APIs using the OpenAPI Specification, an equivalent OpenAPI linter is available.
It identifies common mistakes and inconsistencies in API surfaces:
// Incorrect: Do not use the resource type as the field name here.
message GetBookRequest {
// Field names for resource identifiers in Get requests must be `name`.
// Tools and standards expect this for consistency and interoperability.
string book = 1;
}When able, it also offers a suggestion for the correct fix.
// Correct: This version follows AEP-148, which requires resource identifiers in Get requests to use the field name `name`.
// See https://aep.dev/148/ for details.
message GetBookRequest {
// The name of the book to retrieve.
// Format: publishers/{publisher}/books/{book}
string name = 1;
}The AEP API linter does not follow semantic versioning. Semantic versioning is challenging for a tool like a linter because the addition or correction of virtually any rule is "breaking" (in the sense that a file that previously reported no problems may now do so).
Therefore, the version numbers refer to the linter's core interface. In general:
- Releases with only documentation, chores, dependency upgrades, and/or bugfixes are patch releases.
- Releases with new rules (or potentially removed rules) are minor releases.
- Releases with core interface alterations are major releases. This could include changes to the internal Go interface or the CLI user interface.
Note: Releases that increment the Go version will be considered minor.
This is an attempt to follow the spirit of semantic versioning while still being useful.
If you are interested in contributing to the API linter, please review the contributing guide to learn more.
This software is made available under the Apache 2.0 license.