0.1.208 • Published 4 years ago
@azure-tools/adl.rules.azure v0.1.208
ADL - An Api Description Language using TypeScript
Goals today:
- parse and persist an ADL model
- convert from/to OpenAPI (as much as we can)
- some docs that illustrate the ideas
Aspiration
An alternative to OpenAPI, Swagger means of descrbing an API surface, that facilitates describing multiple API versions of an API.
- provide a better authoring experience for OpenAPI specifications
- handle multiple api-versions without significantly increasing complexity.
- provide a more natural language for expressing an API surface
- protocol agnostic
- existing tools available, not reinventing the wheel.
Reasoning
OpenAPI is a fairly valuable standard for generating wire-protocol documentation for Http APIs.
Unfortunately, it has a few pain-points, that ratchet up the complexity the deeper you get:
- multiple API versions - docmenting an evolving surface
- multipe files ($refs as a means to connect pieces is fragile.)
- YAML/JSON as an encoding format renders the content to be merely data.
- JSON Schema lacks sufficent fidelity to manage a lot of cases easily
- content aware editors are nearly non-existant
- Path Centric model taints the API both in design and expression
Alternatives
Of course, there are an incredible number of ways to document APIs:
- OpenAPI - YAML/JSON
- Smithy -
- RAML -
- GraphQL -
- CSDL
Priorities
In deciding a path,
- Leverage existing tooling as much as possible
- Language should be able to capture an API, however it's constructed
- Project-specific linting/constraints should easy to build and enforce
- Typical change scenarios need to have the lowest friction
0.1.208
4 years ago
0.1.207
4 years ago
0.1.205
4 years ago
0.1.203
4 years ago
0.1.202
4 years ago
0.1.201
4 years ago
0.1.200
4 years ago
0.1.199
4 years ago
0.1.198
4 years ago
0.1.197
4 years ago
0.1.196
4 years ago
0.1.195
4 years ago
0.1.194
4 years ago
0.1.192
4 years ago
0.1.193
4 years ago
0.1.191
4 years ago
0.1.181
4 years ago
0.1.180
4 years ago
0.1.178
4 years ago
0.1.177
4 years ago
0.1.175
4 years ago
0.1.174
4 years ago
1.0.164
4 years ago
0.1.170
4 years ago
1.0.167
4 years ago
0.1.169
4 years ago
1.0.163
4 years ago
1.0.159
4 years ago
1.0.158
4 years ago
1.0.157
4 years ago