Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix links with backticks. #207

Merged
merged 1 commit into from
Aug 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions aep/general/0122/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ ID for the publisher, and `les-miserables` is the resource ID for the book.
- User-settable IDs **should not** be permitted to be a UUID (or any value
that syntactically appears to be a UUID).
- Field annotations **should** use [protovalidate][] in protobuf and [JSON
Schema keywords][] like [`pattern`][] with OAS/JSON Schema.
Schema keywords][] like [pattern][pattern] with OAS/JSON Schema.
- If resource IDs are not user-settable, the API **should** document the basic
format, and any upper boundaries (for example, "at most 63 characters").
- For more information, see the [create][] standard method.
Expand Down Expand Up @@ -320,5 +320,5 @@ alone is strictly necessary, the field **should** use an `_id` suffix (e.g.

<!-- prettier-ignore-start -->
[protovalidate]: https://github.com/bufbuild/protovalidate
[`pattern`]: https://json-schema.org/understanding-json-schema/reference/string#regexp
[pattern]: https://json-schema.org/understanding-json-schema/reference/string#regexp
<!-- prettier-ignore-end -->
18 changes: 10 additions & 8 deletions aep/general/0151/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,17 @@ amount of time" depending on what work is being done. A good rule of thumb is

### Operation representation

The response to a long-running request **must** be an [`Operation`][].
The response to a long-running request **must** be an [`Operation`][Operation].

{% tab proto %}

Protocol buffer APIs **must** use the common component [`aep.api.Operation`][].
Protocol buffer APIs **must** use the common component
[`aep.api.Operation`][aep.api.Operation].

{% tab oas %}

OpenAPI services **must** use this [`JSON Schema Operation`][] schema.
OpenAPI services **must** use this [`JSON Schema Operation`]JSON Schema
Operation] schema.

{% endtabs %}

Expand Down Expand Up @@ -98,8 +100,8 @@ canonical error object.

{% tab proto %}

When using protocol buffers, the common component [`aep.api.Operation`][] is
used.
When using protocol buffers, the common component
[`aep.api.Operation`][aep.api.Operation] is used.

{% sample 'lro.proto', 'rpc WriteBook' %}

Expand Down Expand Up @@ -161,7 +163,7 @@ used.
[lro]: https://github.com/aep-dev/aep/blob/main/proto/aep-api/aep/api/operations.proto
[node.js promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
[future]: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future
[`Operation`]: https://github.com/aep-dev/aep/blob/main/schemas/api/operation.md
[`aep.api.Operation`]: https://buf.build/aep/api/docs/main:aep.api#aep.api.Operation
[`JSON Schema Operation`]: https://github.com/aep-dev/aep/blob/main/json_schema/api/operation.yaml
[Operation]: https://github.com/aep-dev/aep/blob/main/schemas/api/operation.md
[aep.api.Operation]: https://buf.build/aep/api/docs/main:aep.api#aep.api.Operation
[JSON Schema Operation]: https://github.com/aep-dev/aep/blob/main/json_schema/api/operation.yaml
<!-- prettier-ignore-end -->
23 changes: 12 additions & 11 deletions aep/general/0155/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ message CreateBookRequest {
}
```

- [`aep.api.IdempotencyKey`][] has a `key` and a `first_sent` timestamp.
- [`aep.api.IdempotencyKey`][IdempotencyKey] has a `key` and a `first_sent`
timestamp.

- `key` is simply a unique identifier.

Expand All @@ -70,7 +71,7 @@ message CreateBookRequest {
- APIs **should** honor idempotency keys for at least an hour.
- When using protocol buffers, idempotency keys that are UUIDs **must** be
annotated with a minimum lifetime using the extension
[`(aep.api.field_info).minimum_lifetime`][].
[`(aep.api.field_info).minimum_lifetime`][minimum_lifetime].

- 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).
Expand Down Expand Up @@ -107,12 +108,6 @@ field; we define `idempotency_key` instead for two reasons:
API server, and might want to issue multiple requests with the same
`idempotency_key` and trace the behavior of each request separately.

<!-- prettier-ignore-start -->
[idempotency-key-draft]: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
[`aep.api.IdempotencyKey`]: https://buf.build/aep/api/file/main:aep/api/idempotency_key.proto#L21
[`(aep.api.field_info).minimum_lifetime`]: https://buf.build/aep/api/file/main:aep/api/field_info.proto#L35
<!-- prettier-ignore-end -->

### Using UUIDs for request identification

When a value is required to be unique, leaving the format open-ended can lead
Expand All @@ -125,9 +120,9 @@ for collisions when done correctly.
- **2023-23-20**: Adopt AEP from from Google's AIP with the following changes:
- Rename field from `request_id` to `idempotency_key` (plus some minor
releated rewording).
- Add a common component [`aep.api.IdempotencyKey`][] and use this rather
than `string` for the `idempotency_key` field; add related guidance about
`IdempotencyKey.first_seen`.
- Add a common component [`aep.api.IdempotencyKey`][IdempotencyKey] and use
this rather than `string` for the `idempotency_key` field; add related
guidance about `IdempotencyKey.first_seen`.
- Remove guidance about annotating `idempotency_key` with
`(google.api.field_info).format`.
- Add guidance about annotating `idempotency_key` with
Expand All @@ -140,3 +135,9 @@ for collisions when done correctly.
- **2023-10-02**: Add UUID format extension guidance.
- **2019-08-01**: Changed the examples from "shelves" to "publishers", to
present a better example of resource ownership.

<!-- prettier-ignore-start -->
[idempotency-key-draft]: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
[IdempotencyKey]: https://buf.build/aep/api/file/main:aep/api/idempotency_key.proto#L21
[minimum_lifetime]: https://buf.build/aep/api/file/main:aep/api/field_info.proto#L35
<!-- prettier-ignore-end -->
Loading