diff --git a/aep/general/0140/aep.md.j2 b/aep/general/0140/aep.md.j2 index 16240ae6..860fd271 100644 --- a/aep/general/0140/aep.md.j2 +++ b/aep/general/0140/aep.md.j2 @@ -144,9 +144,55 @@ base64-encode a field into a `string` field. ### URIs -Field names representing URLs or URIs **should** always use `uri` rather than -`url`. This is because while all URLs are URIs, not all URIs are URLs. Field -names **may** use a prefix in front of `uri` as appropriate. +Field names representing arbitrary URIs **should** use `uri`. In particular, +note that URLs are URIs but not all URIs are URLs. + +Field names that can only represent a URL **should** use `url`. + +Field names **may** use a prefix in front of `uri` or `url` as appropriate. + +{% tab proto %} + +```proto +message Book { + string name = 1 [(google.api.field_behavior) = IDENTIFIER]; + // A URL pointing to an image of the book. + string image_url = 2; + // A URI identifying the book. + // This could be an ISBN or a URL. + string uri = 3; +} +``` + +{% tab oas %} + +```json +{ + "components": { + "schemas": { + "book": { + "properties": { + "image_url": { + "type": "string", + "format": "uri", + "description": "A URL pointing to an image of the book." + }, + "uri": { + "type": "string", + "format": "uri", + "description": "A URI identifying the book. This could be an ISBN or a URL." + } + } + } + } + } +} +``` + +{% endtabs %} + +**Note:** APIs that have previously used `uri` for URL fields may continue to +do so to avoid unnecessary API changes and to preserve local consistency. ### Reserved words diff --git a/aep/general/0155/aep.md.j2 b/aep/general/0155/aep.md.j2 index ca32c226..f07e70b1 100644 --- a/aep/general/0155/aep.md.j2 +++ b/aep/general/0155/aep.md.j2 @@ -48,13 +48,10 @@ message CreateBookRequest { - [`aep.api.IdempotencyKey`][IdempotencyKey] has a `key` and a `first_sent` timestamp. - - `key` is simply a unique identifier. - Providing an idempotency key **must** guarantee idempotency. - - If a duplicate request is detected, the server **must** return one of: - - A response equivalent to the response for the previously successful request, because the client most likely did not receive the previous response. @@ -75,7 +72,6 @@ message CreateBookRequest { - The `idempotency_key` field **must** be provided on the request message to which it applies (and it **must not** be a field on resources themselves). - - The `first_sent` field can be used by API servers to determine if a key is expired. API servers **must** reject requests with expired keys, and **must** reject requests with keys that are in the future. When feasible, diff --git a/pages/general/tooling-and-ecosystem.md b/pages/general/tooling-and-ecosystem.md index eeac2e1e..1f67591b 100644 --- a/pages/general/tooling-and-ecosystem.md +++ b/pages/general/tooling-and-ecosystem.md @@ -3,6 +3,43 @@ In addition to an API design specification, AEPs also provide an ecosystem of tooling to help produce and interact with these APIs. +## Tools + +Get started quickly with these essential tools: + +**Developer Tools** + +- **[terraform-provider-aep](https://github.com/aep-dev/terraform-provider-aep)** - + Terraform provider for AEP-compliant APIs +- **[aepcli](https://github.com/aep-dev/aepcli)** - Command-line interface for + AEP-compliant APIs +- **[aep-explorer](https://github.com/aep-dev/aep-explorer)** - Interactive web + UI for AEP-compliant APIs +- **[aepc](https://github.com/aep-dev/aepc)** - Generates AEP-compliant RPCs + from proto messages + +**Linting & Validation** + +- **[aep-proto-linter](https://github.com/aep-dev/api-linter)** - Lint gRPC + definitions for AEP compliance +- **[aep-openapi-linter](https://github.com/aep-dev/aep-openapi-linter)** - + Lint OpenAPI definitions for AEP compliance + +**AI** + +- **[aep-mcp-server](https://github.com/aep-dev/aep-mcp-server)** - MCP server + for AEP-compliant APIs +- **[aep.dev/llms.txt](https://aep.dev/llms.txt)** - llms.txt for AEP, to + provide LLMs with knowledge of AEP guidelines. + +**Community Tools** + +We welcome contributions from the community! This section showcases tools built +by the AEP community that extend or complement the official tooling ecosystem. + +- **[aep-typespec](https://github.com/thegagne/aep-typespec)** - Reference + implementation using TypeSpec to generate AEP-compliant OpenAPI Schema. + ## Diagram The following is a diagram that illustrates an end-to-end workflow, including @@ -10,7 +47,7 @@ nodes of tooling that exists, or is intended to be created for the project. Some of the tools in the diagram are not maintained by the AEP project. The diagram is intended to be a complete representation of tools available to help -a user understand how the tools fit in to a development workflow. +a user understand how the tools fit into a development workflow. ```mermaid flowchart TD @@ -31,7 +68,7 @@ flowchart TD hub --> graphql[/GraphQL definitions/] proto --> proto-service(your proto service) proto-service --> http-grpc{{"HTTP REST APIs via grpc-gateway"}} - proto --> proto-linter([aep-proto-linter: lint gRPC definitons for AEP compliance.]) + proto --> proto-linter([aep-proto-linter: lint gRPC definitions for AEP compliance.]) openapi --> http-generated{{api stubs via openapi-generator}} openapi --> oas-linter([aep-openapi-linter: lint OAS definitions for AEP compliance.]) http-generated --> http-service(your http service)