Skip to content

Proposal for v1.0 rc2 #341

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 54 commits into from
Feb 18, 2015
Merged

Proposal for v1.0 rc2 #341

Changes from 1 commit
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
8db6729
V1.0 RC2 WIP
dgeb Dec 24, 2014
e19b2a3
V1.0 RC2 WIP, continued
dgeb Jan 7, 2015
2837f8a
minor edits
Jan 9, 2015
613996e
Introduce `Extending` section.
dgeb Feb 2, 2015
1cd710f
Clarify requirements for meta-information.
dgeb Feb 2, 2015
a42b61d
Introduce pagination.
dgeb Feb 2, 2015
936e1f8
Require dasherized naming of attributes and associations.
dgeb Feb 2, 2015
4d98838
Introduce note about (lack of) inflection rules.
dgeb Feb 2, 2015
6973ee9
Remove HTTP Caching section.
dgeb Feb 2, 2015
dca96b9
Refine Errors section.
dgeb Feb 2, 2015
ea1431e
Fix line breaks and minor typos.
dgeb Feb 2, 2015
25606b9
Clarify requirements around client-generated IDs
dgeb Feb 2, 2015
6133ac1
Correct column wrapping
dgeb Feb 2, 2015
ee12f88
Add note clarifying that foreign keys aren’t attributes.
dgeb Feb 3, 2015
7912e42
Reword note about foreign key relationships
dgeb Feb 3, 2015
e8f0401
Remove "example" divs.
dgeb Feb 3, 2015
ea35fff
Clarify definition of compound documents.
dgeb Feb 3, 2015
1ff22df
Add Recommendations and remove Overview from navigation
dgeb Feb 4, 2015
59b2ee3
Clarify that related resource URLs should remain constant
dgeb Feb 4, 2015
1e23b89
Translate URL rules into "recommendations"
dgeb Feb 4, 2015
e60ccec
Clarify meta information with example.
dgeb Feb 4, 2015
1307997
Clarify top-level self link definition
dgeb Feb 4, 2015
91876ae
Re-introduce filtering strategy as a recommendation.
dgeb Feb 4, 2015
061a8f4
Clarify sorting section
dgeb Feb 4, 2015
825d466
Fix column wrapping
dgeb Feb 4, 2015
8dac29a
Clarify media type header
dgeb Feb 4, 2015
b4d6873
Clarify note about `type` requirement.
dgeb Feb 4, 2015
90d898a
Revisit relationship updating sections.
dgeb Feb 4, 2015
c2a325a
Rename extending -> extensions
dgeb Feb 4, 2015
2ceafea
Move Deleting Resources below Updating Relationships
dgeb Feb 5, 2015
35ee064
Fix typo - remove extra word
dgeb Feb 5, 2015
622a755
Further clarification of updating resources and relationships.
dgeb Feb 5, 2015
43eec5c
Rework extensions page.
dgeb Feb 5, 2015
edd2c10
Move bulk extension page
dgeb Feb 5, 2015
21e9bad
Move patch extension page
dgeb Feb 5, 2015
8af5e05
Clarify resource creation language.
dgeb Feb 5, 2015
2293aa1
Clarify names and media types of official extensions.
dgeb Feb 5, 2015
043adb0
Clarify primary data reqs for to-many relationship updates.
dgeb Feb 5, 2015
c7fa63a
Completely rework the Bulk extension.
dgeb Feb 5, 2015
4a2c55a
Completely rework the Patch extension.
dgeb Feb 6, 2015
b2649b1
Clarify several responses.
dgeb Feb 6, 2015
25b5823
Refactor Patch extension for consistency with base spec.
dgeb Feb 6, 2015
eae7512
Rework Overview page and compound document example.
dgeb Feb 6, 2015
0dbb804
Correct missing comma.
dgeb Feb 7, 2015
d9729e4
Move field name requirements to recommendations.
dgeb Feb 8, 2015
5865f15
Rename 'post' as 'article'
miguelsan Feb 9, 2015
ddb2fdb
Relationships SHALL NOT be named "self"
miguelsan Feb 9, 2015
4ee9bad
Clarify that the *value* of `type` can be singular or plural.
dgeb Feb 10, 2015
0138885
should -> **SHOULD**
dgeb Feb 10, 2015
b35d887
Correct link wrapping
dgeb Feb 17, 2015
2924a6e
Fix EOL spacing.
dgeb Feb 17, 2015
87d2828
Clarify `data` / `errors` top-level members.
dgeb Feb 17, 2015
eece87f
Further define "sort fields" and their usage.
dgeb Feb 17, 2015
2fa6265
Clarify that `type` is not required for empty relationships.
dgeb Feb 18, 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
Next Next commit
Clarify sorting section
  • Loading branch information
@dgeb
dgeb committed Feb 17, 2015
commit 061a8f4784729fb5daa81c478ec71a2925228399
15 changes: 8 additions & 7 deletions format/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -453,23 +453,24 @@ fields in the response.
A server **MAY** choose to support requests to sort resource collections
according to one or more criteria.

An endpoint **MAY** support requests to sort the primary resource type with a
`sort` parameter.
An endpoint **MAY** support requests to sort the primary data with a `sort`
query parameter.

```text
GET /people?sort=age
```

An endpoint **MAY** support multiple sort criteria by allowing comma-separated
fields as the value for `sort`. Sort criteria should be applied in the order
specified.
An endpoint **MAY** support multiple sort criteria by allowing
comma-separated (U+002C COMMA, ",") fields as the value for `sort`. Sort
criteria should be applied in the order specified.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should this "should" be a SHOULD?

Copy link
Member Author

Choose a reason for hiding this comment

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

Good catch - fixed. Thanks @bobholt!


```text
GET /people?sort=age,name
```

The default sort order **SHOULD** be ascending. A `-` prefix on any sort field
specifies a descending sort order.
The default sort order **SHOULD** be ascending. A minus (U+002D:
HYPHEN-MINUS, "-") prefix on any sort field specifies a descending sort
order.

Copy link
Contributor

Choose a reason for hiding this comment

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

It's not clear to me why this is a good trade-off. I don't see that it's particularly bad, either, but does put the added burden on the client to explicitly state a sort order every time.

If JSON API were to set requirements for the first character in field names, it seems like they would tend to match existing programming language requirements. Requiring that field names not start with PLUS, MINUS, or other non-numerical characters doesn't seem like a huge overreach.

Copy link
Member Author

Choose a reason for hiding this comment

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

That's a legitimate take on this - and I can't say that I haven't been on the fence here. We decided on this trade-off so that names would have no restrictions, and to keep sorting requirements only affecting implementations that choose to support sorting. In other words, we wanted to avoid having an optional aspect of the spec driving requirements in a very core part of the spec.

Copy link
Contributor

Choose a reason for hiding this comment

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

For history there's a long discussion on this in #324.

```text
GET /posts?sort=-created,title
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