8000 Attributes of relationships #415 by hhware · Pull Request #431 · json-api/json-api · GitHub
[go: up one dir, main page]
Skip to content

Attributes of relationships #415 #431

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

Closed
wants to merge 3 commits into from
Closed

Attributes of relationships #415 #431

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0eb4408
Attributes of relationships #415 #431: substance
hhware Apr 6, 2015
7315413
Attributes of relationships #415 #431: terminology
hhware Apr 6, 2015
51bb65a
Attributes of relationships #415 #431: optional
hhware Apr 7, 2015
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
Attributes of relationships #415 #431: optional 
Updated on 4/7/15: added the following:
> Linkage objects **MUST** reserve `"links"` member for future use.
  • Loading branch information
@hhware
hhware committed Apr 8, 2015
commit 51bb65abd695e1c9d618a6147db1fe3ff33823ad
87 changes: 65 additions & 22 deletions format/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,10 @@ they represent "[relationship attributes]" and may contain any valid JSON value.
Complex [relationship attributes] **MUST** abide by the same constraints as
[complex resource attributes].

A linkage object **MAY** contain `"meta"` member: non-standard meta-information
about linkage that can not be represented as a [relationship attribute].
Linkage objects **MUST** reserve `"links"` member for future use.

> Note: Resource linkage in a compound document allows a client to link
together all of the included resource objects without having to `GET` any
relationship URLs.
Expand Down Expand Up @@ -817,49 +821,71 @@ GET /articles/1?include=author,comments,comments.author

### Sparse Fieldsets <a href="#fetching-sparse-fieldsets" id="fetching-sparse-fieldsets" class="headerlink"></a>

A client **MAY** request that an endpoint return only specific [fields] in the
response on a per-type basis by including a `fields[TYPE]` parameter.
A client **MAY** request that an endpoint return only specific [fields] and
[relationship attributes] in the response on a per-type basis
by including a `fields[TYPE]` parameter.

> Note: Only [fields] are affected; `type`, `id`, and (optionally) `self` are
included as normal.
> Note: Only [fields] and [relationship attributes] are affected;
`type`, `id`, and (optionally) `self` are included as normal.

The value of the `fields` parameter **MUST** be a comma-separated (U+002C
COMMA, ",") list that refers to the name(s) of the fields to be returned.
COMMA, ",") list that refers to the name(s) of the [fields] and
[relationship attributes] to be returned.
[Relationship attributes] **MUST** be specified via dot-separated
(U+002E FULL-STOP, ".") path which includes the following elements:
`links`, name of the relationship, name of the [relationship attribute].

If a client requests a restricted set of [fields] and [relationship attributes],
an endpoint **MUST NOT** include additional [fields] and
[relationship attributes] in the response.

If a client requests a restricted set of [fields], an endpoint **MUST NOT**
include additional [fields] in the response.
An example for [fields]:

```http
GET /articles?include=author&fields[articles]=title,body&fields[people]=name
```

An example which includes [relationship attributes]:

```text
GET /articles?include=author,publications&fields[articles]=title,links.publications.publication_type&fields[people]=name
```

### Sorting <a href="#fetching-sorting" id="fetching-sorting" class="headerlink"></a>

A server **MAY** choose to support requests to sort resource collections
according to one or more criteria ("sort fields").
A server **MAY** choose to support requests to sort primary resource collections
and linkage object arrays according to one or more criteria ("sort fields").

> Note: Although recommended, sort fields do not necessarily need to
correspond to resource attribute and association names.
correspond to names of [resource attribute], relationships and
[relationship attributes].

> Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") sort
fields be used to request sorting based upon relationship attributes. For
example, a sort field of `+author.name` could be used to request that the
primary data be sorted based upon the `name` attribute of the `author`
relationship.
fields be used to request sorting of primary data based upon
[resource attributes] of related resources. For example, a sort field of
`+author.name` could be used to request that the primary data be sorted
based upon the `name` attribute of the `author` relationship.

An endpoint **MAY** support requests to sort the primary data with a `sort`
query parameter. The value for `sort` **MUST** represent sort fields.
An endpoint **MAY** support requests to sort objects constituting reposnse
with a `sort[PATH]` query parameter. The value of `PATH` **MUST** represent
path to the object being sorted within the response object. The value of
`sort[PATH]` **MUST** represent sort fields.

```http
GET /people?sort=+age
> Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") fields
be used to define `PATH` to the object being sorted within the response object.

For example, to sort primary data:

```text
GET /people?sort[data]=+age
```

An endpoint **MAY** support multiple sort fields by allowing comma-separated
(U+002C COMMA, ",") sort fields. Sort fields **SHOULD** be applied in the
order specified.

```http
GET /people?sort=+age,+name
```text
GET /people?sort[data]=+age,+name
```

The sort order for each sort field **MUST** be specified with one of the
Expand All @@ -872,8 +898,8 @@ following prefixes:
order, JSON API avoids setting requirements for the first character in sort
field names.

```http
GET /articles?sort=-created,+title
```text
GET /articles?sort[data]=-created,+title
```

The above example should return the newest articles first. Any articles
Expand All @@ -889,6 +915,23 @@ parameter `sort`, the server **MUST** return elements of the top-level
The server **MAY** apply default sorting rules to top-level `data` if
request parameter `sort` is not specified.

> Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") sort
fields be used to request sorting of relationship linkage object arrays
based upon [relationship attributes] or [resource attributes] of related
resources. It is recommended that mixing of these two criteria be allowed
in one sort request.

The following example (referring to the
<a href="#document-structure-compound-documents">complete example document
with multiple included relationships</a>) should return publications
of the article sorted first by publication type ([relationship attribute])
and then by publication name (related [resource attribute]),
both in ascending alphabetical order:

```text
GET /articles?sort[data.links.publications]=+data.links.publications.publication_type,+name
```

### Pagination <a href="#fetching-pagination" id="fetching-pagination" class="headerlink"></a>

A server **MAY** choose to limit the number of resources returned in a response
Expand Down
0