-
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
Conversation
cc @bobholt |
Thank you for your work on this! |
"Steve Klabnik", | ||
"Dan Gebhardt" | ||
] | ||
} |
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.
There appears to be a comma missing here.
Sad Panda. I can see the benefits, but at the same time it means my team (backend+frontend web+mobile) either changes tons of endpoints or leaves JSONAPI entirely (at least for the time being). Nonetheless, I am +1 on this. |
Looks like a good revision/rewrite of the spec, clarifies a lot of ambiguities. Though I have to say that to many who expected a slow moving spec that will be upgraded extensibly at the 1.0-rc phase, massive breaking changes is a disappointment. +1 though. With regards to versioning I don't see any elaboration on this? How can we expect the |
I'll probably give this a full read on Monday, but in general, positive on removing ambiguities and moving toward marking the spec as stable. Thanks for the heads-up, @tkellen. |
My interest in JSON-API comes from the fact that I think Siren, HAL and Collection+JSON are all very good first steps with respect to designing hypermedia APIs but I'm always on the lookout for new media types that help to improve on those. Unfortunately, JSON-API takes a big step backwards (in my opinion) by making the design decision that entities MUST have an Now, to your credit a) you don't seem to claim that this is a hypermedia format anywhere on your web site (although I think it is implicit in the presence of links) so perhaps this isn't a fair comparison (although you yourselves make comparisons to HAL) and b) I strongly suspect that this is really a compromise design to try and maximize compatibility with existing conventions for APIs (e.g., Ruby on Rails). So, these seem to be explicit design decisions and not something you've overlooked. You are, of course, free to make those decisions and I'm free to not like them. I was just hoping for something that didn't reinforce what I consider to be bad practices (at least when trying to move in the HATEOAS direction). Most people probably think I'm just being a RESTafarian, but the issue for me isn't really about RESTfulness but more about raising awareness of self-discoverable APIs where clients don't need to know/construct URLs for endpoints. |
Two questions, which i would probably have to answer to my colleagues, but i am not sure how:
|
@kevin-brown thanks for the correction - fixed! @aaronshaf you're welcome - hope it meets your needs! @kurko @daliwali As a maintainer of a couple implementations myself, I completely sympathize with your wishes to change the spec slowly and minimize breakages as we approach 1.0. As difficult as this massive set of changes might be to absorb, the goal is to stabilize the spec at 1.0 very soon and avoid such turbulence afterward. My view of the current (rc1) spec is that it's more of a "guidebook" with so much wiggle room that client and server implementations will rarely match up without customization. We've really tried to remove such ambiguities with this PR, and I'm hopeful from your +1s that you agree. @bobholt looking forward to your feedback. @xogeny I feel that JSON API has all the pieces in place to be a hypermedia format, but that full hypermedia support is definitely optional. Self links and richer relationship links would need to be required instead of optional, and it's a good question whether this is a bridge too far for many implementations. Perhaps we should consider a "hypermedia extension" that changes these MAYs to MUSTs? @ahx thanks for your questions. As for our decision to go with dasherized attributes - we wanted to avoid requiring out-of-band knowledge to parse a response. One approach to this in the spec is to say that, for instance, a client MUST convert underscores to dashes (which provides some wiggle room for servers). We took a more direct approach by making the requirement on the server. Let's discuss further. Also, the change from Thanks to everyone so far for your comments and review. I know that this many changes isn't easy to process all at once and can be tough to swallow for those with current implementations. Trust me when I say it hasn't been easy for me either and I am very much looking forward to a stable 1.0. |
I also don't think dasherized attribute is required. I understand that you want people to parse the response to fit the model layer or other things. But it doesn't mean we need to choose a "hard to used directly" attribute format. It feels like increasing the parse difficulty to force people to do right thing. While it doesn't have to be. |
hmm, also I disagree with the dasherized key names as well, seems unnecessary. I would be in favor of dropping any requirement on key naming. |
Are you or @wycats able to provide any insight as to the role that json:api will play with Ember Data? If the plan is for json:api to be supported as the default serializer/adapter format, the changes seem totally worth it (even if they are large and a bit of a pain to deal with for existing implementations). |
@dgeb and @wycats : I've been knee-deep in a MAJOR F# project that I've pretty much had to do 90% of the work on all by myself so far where once the database end is completely set up, will be transformed into a web app. It is a data-heavy app (think: Intellius on steroids but for providing dossiers on NGO's instead of individuals). As of right now, I am writing data to a JSON file. How well will the JSON API play with an F# app? Or at this stage, should I consider changing from writing to JSON to XML and then build a custom F# parser for the XML as part of the app? |
@barelyknown the plan is for Ember Data to have first class support for JSON API. Feedback from Ember Data was a big input into this round of changes. |
@wycats As long as that's the case, I'm all for it. Hopefully we can finalize v1 soon. |
@jacqueline-homan Check out JSONAPI.NET. |
@dgeb Would it be possible to add an example to the pagination section of the document? I read through this section several times and I'm still having trouble visualizing how this is supposed to work. I think an example here would be really helpful. I'm very excited about these changes. Thank you for your hard work. |
Why switch to dasherized key names when that's not a valid format for variables on server or client? Curious what the reason is. Otherwise, I'm very happy to have this stablize on this small set of requirements so we have a target to aim for. |
Dasherized attribute name would be really unfortunate, and would make it cumbersome to consume the API using JavaScript. |
Resource URLs **SHOULD** only be specified by the server and therefore are | ||
typically only included in response documents. | ||
Attribute names **MUST** consist of only lower case alphanumeric characters | ||
and dashes (U+002D: HYPHEN-MINUS, "-"). Attribute names **MUST NOT** begin |
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.
As for our decision to go with dasherized attributes - we wanted to avoid requiring out-of-band knowledge to parse a response @dgeb
Out-of-band knowledge? How's dashes better? In 9 years of work, I've never seen an API using dashes, not even docs mentioning it. I really don't understand this argument. Could you elaborate?
I discussed with @wycats and we've agreed to move attribute and association naming requirements out of the base spec and into the new Recommendations page. I'll elaborate further once I've updated this PR. |
This looks great! (my only comment is that dasherized attribute names feels suboptimal, but it seems like they're already gone) |
I've just amended this PR with a commit to move field naming requirements to the new Recommendations page. We're now treating all names (including those for attributes, associations, and resource types) and URLs as opaque to the spec. This keeps the spec leaner and more flexible. The naming rules did mitigate a potential conflict with default sort order, in which names couldn’t begin with a In hindsight, I think the naming requirement did cross lines, so thanks to everyone for pushing back on it. P.S. We can continue to discuss recommendations well after the spec hits 1.0, so let's do so in more focused issues / PRs after this is merged. |
👍 Thrilled that @dgeb Questions:
@wycats Thrilled to hear that Ember Data is still targeting this, that's why I started JSONAPI.NET in the first place, to facilitate making Ember Data apps (@jacqueline-homan yes, come have a look we'd appreciate your feedback!) |
One more question: It looks as though requesting multiple IDs via a single GET (e.g. |
One question. In the FAQ we read:
What's been out of that, when we are talking about v1.0? Shouldn't it be stable? Has the strategy changed? |
@mitchlloyd there are simple pagination examples on the home page and the extensions page. These both make use of the reserved links ( @SphtKr those are all valid points / questions that I'll try to resolve soon. I need to confer with @steveklabnik and @wycats. @miguelsan we hope to release v1.0 very soon and then maintain the stability mentioned in the FAQ afterward. We're trying to get all the churn out now, so this is a critical time for the spec. |
@wycats is there a timeline for ember data matching this spec? |
@mgenev Stay tuned! You will be happy with the answer! |
@wycats That is such good news. Awesome. |
Usually the name of the resource is the type so why do we need to specify again although there is no need ? (it does not mean we can't specify it when needed) |
@mtparet AFAIK it's to make supporting polymorphic relationships trivial to support, and it greatly simplifies the lookup of resources in client caches/ |
The type is needed for heterogenous collections generally, and polymorphism is a particular case of that. Always having a type makes processing uniform for all cases and avoids the need to partition results into typed collections and the associated problems that come with that, primarily the inability to order results. Having a type as a field of a resourve also means where supported, the type can be changed. |
I know I'm way late on this—I sort of tuned out of JSON-API after @ahacking got me thinking more about annotated, backwards-compatible syntaxes that could be enabled with JSON-LD—but I wanted to offer some feedback. I think these are very good changes overall and I appreciate all the work that @dgeb and others have done to get us here. In particular, I think going all in on the But I am really sad to see that this PR still doesn't enable linking in embedded objects (i.e. #238). We got so close to solving that with #311, so this feels like a step backward. The current resolution to #238 (create new, normalized resources) seems to impose SQL-driven logic on JSON-API API's that may be backed by non-SQL datastores. And it just makes a lot of APIs more complicated: by far, the most annoying aspect of the current API I've built on this spec is the extra, normalized resources I've had to create. If I think there might be a solution to the embedded linking problem that's relatively simple—sort of an adaptation of the ideas in #311 to the changes in v1.0rc2—should I open a new issue for it? Or is this issue considered settled? |
Pardon my naivete, but why can't we support a {
"data": {
"type": "people",
"name": "Victor Mayonnaise",
"address": {
"street": "12 Mean Street",
"links": {
"city": {
"type": "cities",
"id": "123"
},
"state": {
"type": "states",
"id": "12"
},
"country": {
"type": "countries",
"id": "1"
}
}
}
}
} I've read through the relevant threads and never saw this option even floated, so there must be something I'm missing. |
@bintoro those discussions occurred well before the current changes. You should be able to search the issues (which are prossibly closed now). @ethanresnick yes I would like to see specific linking out of rich/complex/embedded fields. In my use cases those rich/complex attributes are not standalone resources and are not addressable at an endpoint, they exist purely as structured fields within a resource. Thanks for opening #369 ! @bintoro I think the links bag applies at a resource object level, not at an arbitrary field level, but I may be wrong. |
@ahacking Looking at #311 again, it appears that what I suggested above was indeed the standard practice sometime in the days of yore, pre-RC1 or so, but was later disallowed. Then #311 came along and proposed to move all links to the top level. Great. However, when that was backtracked on, There's nothing that suggests Unless someone can point out why I also considered maintaining just one {
"data": {
"type": "people",
"name": "Victor Mayonnaise",
"address": {
"street": "12 Mean Street",
},
"links": {
"address.city": {
"type": "cities",
"id": "123"
},
"address.state": {
"type": "states",
"id": "12"
},
"address.country": {
"type": "countries",
"id": "1"
}
}
}
} But this is no good because then |
@bintoro After thinking about this some more, I really like your proposal to nest I also considered a couple other solutions that tried to get the best of the above (i.e. a single I'm going to open up a separate issue for this, since I haven't heard otherwise from @dgeb and it doesn't make sense to keep discussing it in this PR. |
I agree this deserves its own issue for discussion. I begin to lose track of issues once they're closed. Thanks @ethanresnick. |
This represents a fairly thorough rewrite of JSON API by myself and @wycats. This rewrite is based upon feedback we've received and our experience building both client and server implementations of the spec. I regret that changes of this scope and magnitude are proposed in a single pull request, but this has been necessitated by the condensed time in which we had to work.
The overarching goal of this rewrite has been to bring rigor and simplicity to JSON API, transforming it from a loose set of guidelines to a specification that can be fully implemented to create compatible clients and servers. In general, SHOULDs have been minimized and replaced with MUSTs, and any MAYs that remain tend to be paired with MUSTs.
The current spec has been refactored into a base spec, rules for extending it (including official extensions for bulk and patch updates), as well as recommendations (e.g. for forming URLs) that are deemed beyond-the-scope of the spec.
Some of the major changes in the base specification include:
type
andid
members.Attribute and association keys MUST be dasherized (e.g.[Note: no longer a requirement; this has been moved to the new Recommendations page]"first-name"
)."data"
key."linked"
key.links
relate to the primary data, includingself
. Support for URI templates in links has been removed.self
links, relationship URLs (for manipulating the relationship), related resource URLs (for fetching related resource objects), linkage to other objects in a compound document, andmeta
info.page
query param has been reserved. The spec remains agnostic about pagination strategies.filter
query param.Please review and leave general feedback below. I hope we can merge this soon and handle specific concerns in more targeted issues.
Some relevant links to modified pages: