Skip to content

Resource Versioning Profile #1333

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.

Sign up for GitHub

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

Open
wants to merge 27 commits into
base: gh-pages
Choose a base branch
from
Open

Resource Versioning Profile #1333

Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
df9838a
Create resource-versioning index.md.
gabesullice Dec 12, 2018
e815ccd
Add a "Resource Versioning" profile category
gabesullice Dec 13, 2018
c302a8c
Add all editors to this profile
gabesullice Dec 13, 2018
84d4840
Fix spacing
gabesullice Dec 13, 2018
ea9c13c
Use editor format from #1349
gabesullice Dec 20, 2018
9d9e263
move 501 to relative version section
gabesullice Dec 20, 2018
9368cbc
disambiguate bad version negotiator vs. argument errors
gabesullice Dec 20, 2018
d3c1d13
add trailing slash to error type URIs
gabesullice Dec 20, 2018
cac4baf
add linking and version history section
gabesullice Dec 20, 2018
56bc05e
fixup link and version history commit
gabesullice Dec 20, 2018
75659ce
add to and fix link example table
gabesullice Dec 20, 2018
2d5346e
typos and clarification
gabesullice Dec 20, 2018
c351d9c
change the query parameter from snake-case to camel-case
gabesullice Dec 20, 2018
3e4b67e
clarify that a one-segment version identifier is valid
gabesullice Dec 21, 2018
515aba9
invert definition of a version
gabesullice Dec 21, 2018
0feddd6
clarify the example narrative of a version history
gabesullice Dec 21, 2018
b0a1e3d
relax `type` link requirement
gabesullice Dec 21, 2018
f0d73db
clarify interoperability and optionality of version negotiators
gabesullice Dec 21, 2018
a4329d5
the first or only segment of a version identifier must be interpreted…
gabesullice Dec 21, 2018
7a352dc
restrict usage of the rel negotiator in resource objects' `self` links
gabesullice Dec 21, 2018
9129eb2
reduce redundancy
gabesullice Dec 21, 2018
ba9bf0b
use the `source` error object member in error details
gabesullice Dec 21, 2018
6bc95be
disallow custom rel-based version arguments
gabesullice Dec 21, 2018
1a1395d
reorder two lines
gabesullice Dec 21, 2018
e4adbd7
fix some ascii art
gabesullice Dec 21, 2018
5c5b0f4
fix italicization
gabesullice Dec 21, 2018
c82ecbe
update mateu's contact info
gabesullice Dec 21, 2018
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
Prev Previous commit
Next Next commit
clarify interoperability and optionality of version negotiators
  • Loading branch information
@gabesullice
gabesullice committed Dec 21, 2018
commit f0d73db82a26d8ab999b38a582969e112b864351
13 changes: 13 additions & 0 deletions _profiles/drupal/resource-versioning/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,19 @@ If provided, resource objects' `self` links **MUST NOT** be the same.

# Version Negotiators
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Design feedback/interoperable implementations review requirement] If I'm understanding correctly, each server implementation can define its own version negotiators, with multiple servers using the same negotiator name in different ways (and no central registry). That seems not great for interoperability. It would also seem to mean that no other version negotiators can ever be standardized as part of this profile, because they could conflict with existing implementations. Is that really what you want?

My gut instinct would be to make this profile's spec the canonical list of all legal version negotiators. Then, you can add more over time to this spec as they're requested. To support people who really need to use a version negotiator that isn't part of your profile, you could have some set of negotiator names/schemes/namespaces that are allowed to have implementation-specific meanings.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I've done is applied the implementation-specific query parameter name constraints as a version negotiator constraint and added a mechanism for adding new negotiators to the profile.

Changes here: f0d73db

Elsewhere, @e0ipso suggest that we use URIs but I think this is sufficient. @e0ipso, WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc: @wimleers cause it's his inbox that I suggested too 😛

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with that. However I still think that doc curies offer a lower barrier of entry. One could document the new crazy negotiator in their blog and have the server implementation point to that, instead of adding it here.

Many will just not go through the trouble to send their idea to some email addresses and be potentially blocked by them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I wanted to discourage non-standard negotiators being used as a standard and keep them isolated. My feeling was that sending an email saying "hey, I'd like to add a negotiator like this..." doesn't seem like a super high barrier. In some ways, it's even less difficult than opening a PR.

What if we add this:

Note: Don't be shy! New version negotiators are more than welcome, the editors want to see this profile proliferate and that means accepting versioning strategies like yours!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@e0ipso, would that work?


This profile defines a number of version negotiators which a server **MAY**
implement. Additional version negotiator's may be added to this profile at a
later date.

Version negotiators which are not defined by this profile **MUST** adhere to the
same constraints as [implementation-specific query parameter names](https://jsonapi.org/format/1.1/#query-parameters-custom).

It is **RECOMMENDED** that any alternative version negotiators be added to this
profile. New version negotiators may be registered by sending one, joint email
to the profile editors with the subject line: "New JSON:API Resource Version
Negotiator: {negotiator name}". This will begin a process of refinement and/or
result in a determination of fitness for addition to this profile.

## ID-Based Version Negotiator

This profile establishes the `id` version negotiator. An `id`-based version
Expand Down
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy