feat: AIP-162 – Resource revisions #35
Conversation
| particular resource, and intentionally avoid the term _version_, which refers | ||
| to the version of an API as a whole. | ||
|
|
||
| ## Guidance |
There was a problem hiding this comment.
aip/general/0162/aip.md.j2
Outdated
| publishers/123/books/les-miserables@c7cfa2a8 | ||
|
|
||
| **Note:** The `@` character is selected because it is the only character | ||
| permitted by [RFC 1738 §2.2][] for special meaning within a URI scheme that is |
There was a problem hiding this comment.
What is the significance of RFC 1738 (which is obsolete)? https://datatracker.ietf.org/doc/html/rfc3986 is the IETF document most relevant to URLs (and https://datatracker.ietf.org/doc/html/rfc3987 for not-necessarily-ASCII analogs).
There was a problem hiding this comment.
I won't claim any competence at ABNF, but my reading of RFC 3987 section 3.3, particularly this part:
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
is that "@" is allowed in path segments, so using it to designate a revision is fine as long as we are clear that we've taken it for that and it should not be used otherwise.
|
|
||
| **Note:** The `@` character is selected because it is the only character | ||
| permitted by [RFC 1738 §2.2][] for special meaning within a URI scheme that is | ||
| not already used elsewhere. |
There was a problem hiding this comment.
It still seems to carry a collision risk, though—using the example above, what if a book's title itself includes "@"?
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Book' | ||
| /publishers/{publisherId}/books/{bookId}:listRevisions: |
There was a problem hiding this comment.
This deviates too far from RESTful best practices; the path looks like it should return a Book but it actually returns a collection of books. I would feel much more comfortable with modeling revisions as either subresources (e.g., /publishers/{publisherId}/books/{bookId}/revisions) or a parallel collection to the revision-capable resources (e.g., /publishers/{publisherId}/bookRevisions).
| the response. | ||
|
|
||
| If necessary, APIs **may** explicitly support listing child resources across | ||
| parent revisions by accepting the `@-` syntax. For example: |
There was a problem hiding this comment.
This also is quite ugly, I think it's arguing against the @ patterns.
There was a problem hiding this comment.
Note also that it prohibits use of - as a revision identifier.
There was a problem hiding this comment.
Looks good. 👍
@gibson042 and @hudlow make some good points that we should address, but I think that can be done in a follow-on PR if necessary.
I fixed up the oas example -- pls make sure I didn't inadvertently break something.
|
|
||
| - The resource **must** contain a `revision_id` field, which **should** be a | ||
| string and contain a short, automatically-generated random string. A good | ||
| rule of thumb is the last eight characters of a UUID4. |
There was a problem hiding this comment.
| rule of thumb is the last eight characters of a UUID4. | |
| rule of thumb is the last eight characters of a version 4 UUID. |
| the response. | ||
|
|
||
| If necessary, APIs **may** explicitly support listing child resources across | ||
| parent revisions by accepting the `@-` syntax. For example: |
There was a problem hiding this comment.
Note also that it prohibits use of - as a revision identifier.
Changes as agreed in working meeting on 11/15/2022.
No description provided.