Skip to content

Introduce Profiles to v1.1 #1268

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

Merged
merged 30 commits into from
Sep 18, 2018
Merged

Introduce Profiles to v1.1 #1268

Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
9c0b91b
Introduce Profiles to v1.1
dgeb Apr 12, 2018
3f4220f
profiles: tweak definitions a bit
ethanresnick Apr 17, 2018
7533232
profiles: add should about extensibility
ethanresnick Apr 17, 2018
8b51551
profiles: add note about how to serialize space-separated media type …
ethanresnick Apr 17, 2018
fe660ec
profiles: make it a MUST to list the applied profiles in Content-Type
ethanresnick Apr 17, 2018
510e783
profiles: clarify role of profile in `Accept` per prior convos
ethanresnick Apr 17, 2018
36f4c0a
profiles: clarify that `Accept` may be totally ignored
ethanresnick Apr 17, 2018
4085f31
profiles: add example of using Accept to request profile
ethanresnick Apr 17, 2018
e08d3ce
profiles: clarify that keywords must be valid member names
ethanresnick Apr 17, 2018
67ff7f1
profiles: clarify evolution requriments
ethanresnick Apr 17, 2018
51d0be6
profiles: add note about 415 handling from 1.0 servers
ethanresnick Apr 17, 2018
1827986
Add top-level links.profile
ethanresnick Apr 30, 2018
eb2e815
Fix typo and trailing whitespace
dgeb Jul 1, 2018
e0397c2
Use the term `profile` in example (instead of `ext`)
dgeb Jul 1, 2018
7221b18
Clarify that links can specify URIs, not just URLs
dgeb Jul 13, 2018
18b590e
Replace all usages of jsonapi/profiles with links/profile
dgeb Jul 13, 2018
661ddbc
Profiles: fix broken links
ethanresnick Jul 22, 2018
e1232a9
profiles: remove overloaded uses of term "alias"
ethanresnick Jul 22, 2018
1e448f8
profiles: editorial/terminology cleanup/tweaks
ethanresnick Jul 27, 2018
9be7013
profiles: define what a profile is
ethanresnick Jul 27, 2018
7757134
profiles: add must-ignore rule to example timestamps profile
ethanresnick Jul 27, 2018
055a41f
profiles: create separate authoring section
ethanresnick Jul 27, 2018
3599821
profiles: add new minimal extra authoring rules
ethanresnick Jul 27, 2018
7f9eb81
profiles: editorial tweaks
ethanresnick Aug 28, 2018
e151c57
profiles: define handling of unrecognized values
ethanresnick Aug 29, 2018
e666c90
proflies: document extensibility concerns/requirements
ethanresnick Aug 29, 2018
db1e970
profile: define implicit profile query param value
ethanresnick Sep 18, 2018
61ccdff
profiles: clarify shallow definition of elements
ethanresnick Sep 18, 2018
ebae1b5
profiles: small cleanup
ethanresnick Sep 18, 2018
f8770df
profiles: fix profile param value inference
ethanresnick Sep 18, 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
Fix typo and trailing whitespace
  • Loading branch information
@dgeb
dgeb committed Jul 1, 2018
commit eb2e815084ab15561502928586f8d447806b7700
51 changes: 26 additions & 25 deletions _format/1.1/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1825,7 +1825,7 @@ to standard query parameters without conflicting with existing implementations.
## <a href="#profiles" id="profiles" class="headerlink"></a> Profiles

JSON API supports the use of "profiles" as a way to indicate additional
semantics that apply to a JSON:API request/document, without altering the
semantics that apply to a JSON:API request/document, without altering the
basic semantics described in this specification.

[RFC 6906](https://tools.ietf.org/html/rfc6906) covers the nature of profile
Expand All @@ -1838,19 +1838,19 @@ identification:
conforms to a profile. Thus, clients SHOULD treat profile URIs as
identifiers and not as links.

However, to aid human understanding, profile URIs **SHOULD** return
However, to aid human understanding, profile URIs **SHOULD** return
documentation of the profile.

A profile **MAY** assign meaning to particular elements of the document
structure, such as resource attributes or members of meta objects, and even
to query parameters whose behavior is left up to each implementation, such
to query parameters whose behavior is left up to each implementation, such
as `filter` and all those that contain a non a-z character.

The scope of a profile **MUST** be clearly delineated. The elements reserved by
a profile, and the meaning assigned to those elements, **MUST NOT** change over
time or else the profile **MUST** be considered a new profile with a new URI.
The scope of a profile **MUST** be clearly delineated. The elements reserved by
a profile, and the meaning assigned to those elements, **MUST NOT** change over
time or else the profile **MUST** be considered a new profile with a new URI.

Profiles **MAY** be updated over time to add new capabilities. However, any such
Profiles **MAY** be updated over time to add new capabilities. However, any such
changes **MUST** be [backwards and forwards compatible](http://www.w3.org/2001/tag/doc/versioning-compatibility-strategies#terminology),
in order to not break existing users of the profile. This requirement usually
limits changes to adding optional keys within objects specified in the profile's
Expand All @@ -1864,12 +1864,12 @@ object. But it could not make that member required, nor could it introduce
a new sibling to `timestamps`.

Profiles **SHOULD** reserve at least one object-valued member, and **SHOULD**
Copy link
Contributor

Choose a reason for hiding this comment

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

This comes as a surprise to me. This means that a spec like Drupal's Fancy Filters is violates this recommendation. OTOH, Partial Success would comply (it reserves the errors key in meta objects).

So what about profiles that define behavior for reserved query parameters, such as filter?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, this was written with profiles that add data to the document in mind, not those that just use query parameters. Although, on second thought, it's probably a good idea even for a profile like fancy filters to reserve a key (probably somewhere in meta) so that, if it ever wants to add some metadata to the response (e.g., the size of the unfiltered set, or a deprecation warning or something), it can do so.

Copy link
Member Author

Choose a reason for hiding this comment

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

We can probably clarify intent here by saying something like:

In order to support the potential to add features over time, profiles SHOULD reserve at least one object-valued member in any portion of the document in which they may realistically expand in the future.

consider reserving an object-valued member anywhere they expect to potentially
consider reserving an object-valued member anywhere they expect to potentially
add new features over time.

> Note: When a profile changes its URI, a huge amount of interoperability is lost.
> Users that reference the new URI will have their messages not understood by
> implementations still aware only of the old URI, and vice-versa.
> implementations still aware only of the old URI, and vice-versa.
> Accordingly, the advice above is aimed at allowing profifiles to grow
> without needing to change their URI.

Expand All @@ -1889,14 +1889,14 @@ The `profile` media type parameter is used to describe the application of
one or more profiles to the JSON API media type. The value of the `profile`
parameter **MUST** equal a space-separated (U+0020 SPACE, " ") list of profile URIs.

> Note: When serializing the `profile` media type parameter, the HTTP
> specification requires that its value be surrounded by quotation marks
> Note: When serializing the `profile` media type parameter, the HTTP
> specification requires that its value be surrounded by quotation marks
> (U+0022 QUOTATION MARK, "\"") if it contains more than one URI.

A client **MAY** use the `profile` media type parameter in conjunction with the
JSON API media type in an `Accept` header to _request_, but not _require_, that
the server apply one or more profiles to the response document. When such a
request is received, a server **SHOULD** attempt to apply the requested profiles
the server apply one or more profiles to the response document. When such a
request is received, a server **SHOULD** attempt to apply the requested profiles
to its response.

For example, in the following request, the client asks that the server apply the
Expand All @@ -1911,7 +1911,7 @@ Accept: application/vnd.api+json;profile="http://jsonapi.org/extensions/last-mod
It is used to support old servers that don't understand the profile parameter.

Servers **MAY** add profiles to a JSON API document even if the client has not
requested them. The recipient of a document **MUST** ignore any profile extensions
requested them. The recipient of a document **MUST** ignore any profile extensions
in that document that it does not understand. The only exception to this is profiles
whose support is required using the `profile` query parameter, as described below.

Expand All @@ -1921,12 +1921,12 @@ Clients and servers **MUST** include the `profile` media type parameter in
conjunction with the JSON API media type in a `Content-Type` header to indicate
that they have applied one or more profiles to a JSON API document.

Likewise, clients and servers applying profiles to a JSON API document **MUST**
include a [top-level][top level] [`links` object][links] with a `profile` key,
and that `profile` key **MUST** include a [link] to the URI of each profile
Likewise, clients and servers applying profiles to a JSON API document **MUST**
include a [top-level][top level] [`links` object][links] with a `profile` key,
and that `profile` key **MUST** include a [link] to the URI of each profile
that has been applied.

When an older JSON API server that doesn't support the `profile` media type
When an older JSON API server that doesn't support the `profile` media type
parameter receives a document with one or more profiles, it will respond with a
`415 Unsupported Media Type` error.

Expand All @@ -1937,24 +1937,25 @@ type parameter. If this resolves the error, the client **SHOULD NOT** attempt to
use profile extensions in subsequent interactions with the same API.

> The most likely other causes of a 415 error are that the server doesn't
support JSON API at all or that the client has failed to provide a required
support JSON API at all or that the client has failed to provide a required
profile.

### <a href="#profile-query-parameter" id="profile-query-parameter" class="headerlink"></a> `profile` Query Parameter

A client **MAY** use the `profile` query parameter to _require_ the server to
apply one or more profiles when processing the request. The value of the `profile`
apply one or more profiles when processing the request. The value of the `profile`
query parameter **MUST** equal a URI-encoded whitespace-separated list of profile URIs.

If a server receives a request requiring the application of a profile or
combination of profiles that it can not apply, it **MUST** respond with a `400
Bad Request` status code.

> Note: When a client lists a profile in the `Accept` header, it's asking the server
> to compute its response as normal, but then send the response document with some
> extra information, as described in the requested profile. By contrarst, when a client
> lists a profile in the `profile` *query parameter*, it's asking the server to *process
> the incoming request* according to the rules of the profile.
> Note: When a client lists a profile in the `Accept` header, it's asking the
> server to compute its response as normal, but then send the response document
> with some extra information, as described in the requested profile. By
> contrast, when a client lists a profile in the `profile` *query parameter*,
> it's asking the server to *process the incoming request* according to the
> rules of the profile.

### <a href="#profile-descriptors" id="profile-descriptors" class="headerlink"></a> Profile Descriptors

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