-
Notifications
You must be signed in to change notification settings - Fork 890
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.
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
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 e19b2a3
V1.0 RC2 WIP, continued
dgeb 2837f8a
minor edits
613996e
Introduce `Extending` section.
dgeb 1cd710f
Clarify requirements for meta-information.
dgeb a42b61d
Introduce pagination.
dgeb 936e1f8
Require dasherized naming of attributes and associations.
dgeb 4d98838
Introduce note about (lack of) inflection rules.
dgeb 6973ee9
Remove HTTP Caching section.
dgeb dca96b9
Refine Errors section.
dgeb ea1431e
Fix line breaks and minor typos.
dgeb 25606b9
Clarify requirements around client-generated IDs
dgeb 6133ac1
Correct column wrapping
dgeb ee12f88
Add note clarifying that foreign keys aren’t attributes.
dgeb 7912e42
Reword note about foreign key relationships
dgeb e8f0401
Remove "example" divs.
dgeb ea35fff
Clarify definition of compound documents.
dgeb 1ff22df
Add Recommendations and remove Overview from navigation
dgeb 59b2ee3
Clarify that related resource URLs should remain constant
dgeb 1e23b89
Translate URL rules into "recommendations"
dgeb e60ccec
Clarify meta information with example.
dgeb 1307997
Clarify top-level self link definition
dgeb 91876ae
Re-introduce filtering strategy as a recommendation.
dgeb 061a8f4
Clarify sorting section
dgeb 825d466
Fix column wrapping
dgeb 8dac29a
Clarify media type header
dgeb b4d6873
Clarify note about `type` requirement.
dgeb 90d898a
Revisit relationship updating sections.
dgeb c2a325a
Rename extending -> extensions
dgeb 2ceafea
Move Deleting Resources below Updating Relationships
dgeb 35ee064
Fix typo - remove extra word
dgeb 622a755
Further clarification of updating resources and relationships.
dgeb 43eec5c
Rework extensions page.
dgeb edd2c10
Move bulk extension page
dgeb 21e9bad
Move patch extension page
dgeb 8af5e05
Clarify resource creation language.
dgeb 2293aa1
Clarify names and media types of official extensions.
dgeb 043adb0
Clarify primary data reqs for to-many relationship updates.
dgeb c7fa63a
Completely rework the Bulk extension.
dgeb 4a2c55a
Completely rework the Patch extension.
dgeb b2649b1
Clarify several responses.
dgeb 25b5823
Refactor Patch extension for consistency with base spec.
dgeb eae7512
Rework Overview page and compound document example.
dgeb 0dbb804
Correct missing comma.
dgeb d9729e4
Move field name requirements to recommendations.
dgeb 5865f15
Rename 'post' as 'article'
miguelsan ddb2fdb
Relationships SHALL NOT be named "self"
miguelsan 4ee9bad
Clarify that the *value* of `type` can be singular or plural.
dgeb 0138885
should -> **SHOULD**
dgeb b35d887
Correct link wrapping
dgeb 2924a6e
Fix EOL spacing.
dgeb 87d2828
Clarify `data` / `errors` top-level members.
dgeb eece87f
Further define "sort fields" and their usage.
dgeb 2fa6265
Clarify that `type` is not required for empty relationships.
dgeb File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Rename 'post' as 'article'
An specification must avoid wording with double meaning. The word "POST" is already covered by the corresponding HTTP verb. It should not appear again in the examples with another potentially confusing signification. This makes searching easier too.
- Loading branch information
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.