Uh oh!
There was an error while loading. Please reload this page.
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.
| 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.
mkistler
left a comment
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.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
| - 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.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Changes as agreed in working meeting on 11/15/2022.
No description provided.