https://github.com/aep-dev/api-linter
A linter for APIs defined in protocol buffers.
https://github.com/aep-dev/api-linter
Last synced: 4 months ago
JSON representation
A linter for APIs defined in protocol buffers.
- Host: GitHub
- URL: https://github.com/aep-dev/api-linter
- Owner: aep-dev
- License: apache-2.0
- Created: 2024-04-09T04:43:36.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-13T18:34:32.000Z (5 months ago)
- Last Synced: 2026-01-13T20:56:24.548Z (5 months ago)
- Language: Go
- Homepage:
- Size: 4.54 MB
- Stars: 6
- Watchers: 1
- Forks: 7
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# AEP Protobuf Linter
[](https://github.com/aep-dev/api-linter/actions/workflows/ci.yaml)
The API linter provides real-time checks for compliance with many of the API
standards, documented using [API Enhancement Proposals](https://aep.dev). It operates on API
surfaces defined in [protocol buffers][].
For APIs using the
[OpenAPI Specification][], an equivalent [OpenAPI linter](https://github.com/aep-dev/aep-openapi-linter) is
available.
It identifies common mistakes and inconsistencies in API surfaces:
```proto
// 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.
```proto
// 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;
}
```
[_Read more ≫_](docs/index.md)
## Versioning
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.
## Contributing
If you are interested in contributing to the API linter, please review the [contributing guide](https://aep.dev/contributing/) to learn more.
## License
This software is made available under the [Apache 2.0][] license.
[apache 2.0]: https://www.apache.org/licenses/LICENSE-2.0
[api improvement proposals]: https://aip.dev/
[protocol buffers]: https://developers.google.com/protocol-buffers
[OpenAPI specification]: https://www.openapis.org/
[OpenAPI specification linter]: https://github.com/aep-dev/aep-openapi-linter