I find that a lot of developers will use the briefer implicit return form (`transform => backup.sync(transform)`) of a function without focusing on whether the returned value has significance.
I wanted to write out the explicit `return` form of the handler to emphasize that returning a promise in an Orbit event handler has significance. It delays resolution of the event, thereby allowing listeners to participate in that resolution.
Perhaps it was unnecessary for me to _also_ include the implicit return form in that example. However, that's the way I would normally write this function, and I'd like to present "best practices" and show how concise the code is typically.
Developers from several large public-facing sites have already told me that they're using engines in production. In fact, Kacey Coughlin is giving a talk tonight at the SF Ember meetup about LinkedIn's experience using engines [1]. Granted, the talk is titled "On the Bleeding Edge with Ember Engines", which fairly points out that there are some rough edges left to smooth over.
Still, I think it's a pretty good time to start exploring engines. I'd say that the feature should be quite stable by the time 2.8 stable ships. Plus, we should have a preliminary lazy-loading story finished by then, which has the potential to really impact your app's perceived performance.
> JSON/REST are beloved because it's simple and just works.
There is no consensus on the details of "REST". Every implementation has its subtle quirks and solutions to the same basic problems. Every client library must be customized to adapt to these differences. Since the fundamental aspects aren't agreed upon, there is little chance of defining compatible features at a higher level.
On the other hand, the value proposition for JSON API is rooted in consensus [1]
JSON API has been proven in many languages and frameworks. The JSON API team is diverse and has only one member on the Ember core team (@wycats). More importantly, JSON API has been influenced by hundreds of contributors with diverse backgrounds and specialties.
At this point, JSON API is pretty far from its original extraction from Ember Data. It has come full circle to the point that a JSON API Adapter is being written from scratch for Ember Data (and is now almost fully compatible).
> On the other hand, the value proposition for JSON API is rooted in consensus [1]
> JSON API has been proven in many languages and frameworks. The JSON API team is diverse and has only one member on the Ember core team (@wycats). More importantly, JSON API has been influenced by hundreds of contributors with diverse backgrounds and specialties.
CORBA (one of the cited failed examples above) is notable for having been rooted in consensus. It pulled together dozens of use-cases from all over industry... and became a giant, hulking, overly complex, unpleasant-to-use mess.
I guess I'm confused then. If I wanted a complicated standard but one with broad consensus and lots of library support behind it, why wouldn't I just use XML-RPC? Other than not being XML, what does JSON API offer? Because at first glance, it looks just about as verbose and unfriendly as XML-RPC to me.
Json-rpc it's what you get anyway most of the time since very few have a clue of what rest is. Not that is a bad design by itself, many of them are concise and workable without being rest.
What I am concerned mostly is the added overhead of fitting everything under a single standard. Sometime you need state aware api, sometime you need data retrieval api, sometime you need to expose a remote interface to constraint manipulating objects with server side rules.
Why it all has to be a standard escapes me. You mostly get absurdly convoluted operation when you try to fit one model under another.
JSON API adheres to RESTful principles and constraints: it uses HTTP verbs to fetch and manipulate resources and provides allowances for hypermedia. XML-RPC is neither RESTful nor supportive of hypermedia and has no place in building a REST API.
As a co-author of JSON API, I'd like to address the value proposition of the specification.
First of all, JSON API provides guidance for a lot of API design decisions that are usually contentious because, although they may seem trivial, they must be made with care in order to be consistent and viable. For instance, JSON API provides guidance for:
* fetching related resources together with primary resources in order to minimize requests
* limiting the fields included in a response document in order to minimize payload size
* paginating data with links that work well with any pagination strategy (page-based, offset-based, and cursor-based)
* sorting results, even potentially based on related resource fields
* representing heterogeneous collections and polymorphic relationships
* representing errors
In my opinion, some of the most useful guidance is related to the representation of relationships, which can include:
* embedded linkage data which "links" primary resources with related resources in a compound document.
* relationship URLs which can retrieve linkage data and directly manipulate the relationship without affecting the underlying resources.
* related resource URLs which can retrieve related resources themselves.
In addition, JSON API supports extensions and has official extensions for performing bulk updates and JSON Patch operations. These particular extensions provide extremely useful mechanisms for transactionally working with multiple resources.
All of this guidance has been forged over the course of two years based on the feedback and contributions of hundreds of developers. Even if you were to incorporate some of this guidance in your APIs piecemeal, it would probably save your team many hours of design discussions.
However, the bigger value proposition of JSON API is just now beginning to be realized. Since we've tightened the "spec" into a proper spec by eliminating many MAYs and SHOULDs, it is now possible to reliably build implementations with a guarantee of compatibility. It's regrettable that it took us so long to move from providing loose guidelines to a more rigid spec, but I truly believe that the awkward intermediate phase provided invaluable feedback that ultimately informed the design of the spec and will improve adoption of 1.0.
We are seeing client libraries being built in JavaScript, iOS, and Ruby, and server libraries in PHP, Node.js, Ruby, Python, Go, and .NET. Although not all are (yet) compliant with the latest changes to the spec, we are tracking progress carefully as the spec nears 1.0 to ensure that we smooth over any rough spots encountered by implementors. I'm personally involved in developing Orbit.js and JSONAPI::Resources, both of which are nearing JSON API compliance.
I can say that it's incredibly satisfying to build applications with compatible client and server libraries. It lets me focus on the design of my application's domain instead of myriad details related to transforming data representations and protocol usage. Even better is the knowledge that other clients can easily use my API and all of its advanced features, regardless of their language and framework. This is ultimately the promise of JSON API, and it won't be long before it's realized.
Five years ago, much of my team's time was being consumed fighting with the WSDL and SOAP specs, and their various subtly incompatible or outright broken implementations on our target platforms.
A switch to JSON-RPC 2.0 meant everyone now understood the entirety of the specifications our APIs relied on, and if we couldn't find a good implementation for our target, we could either fix one, or write one ourselves in just a few hours.
The productivity gain was effectively infinite.
I look at the JSON API specification in all its architecture astronaut glory, and weep.
I like the Broccoli name quite a bit (and the whole concept and implementation - great job Jo!), but I also prefer `Brocfile` to `Broccolifile`. Does that make me a broccoliphile against broccolifiles?
Hi, I'm the developer of Orbit, which I created to enable advanced features in client-side apps such as offline mode, synchronization of local caches, undo / redo stacks, and ad hoc editing contexts. These features require a systematic approach to accessing and transforming data in multiple data sources.
Stay tuned - I'm currently working on an introductory blog post as well as detailed docs and an example app.
Edit: I just updated the readme with essentially the same use cases I mentioned above.
I've had this name and concept kicking around in my head for over two years. "Orbit" seems a catchy metaphor for effortless relationships between data sources.
I'd hoped there wouldn't be confusion with a component in such a different domain (image slider vs. data), but I will consider a rename if that proves to not be the case.
Fwiw, ZURB's Orbit was my first thought too, and mattdeboard is right that changing the name will only get harder not easier.
That said, it's probably also the case that most of us will just make note of the fact that there are two Orbit.js's now and qualify which one we're referring to when needed.
There's already a significant level of confusion between the two products. The decision to change will not get any easier and the impact of a name change will only increase as you drag on. You should change it now because there's nothing gained by waiting.
I approve! One of the most annoying aspects of OS X (pre-Lion) was hunting for the lower right corner to resize windows. Thankfully, all sides of a window can now be used for resizing. This is a good vision for extending ease-of-resizing further.
It would also force the priority of responsive design. Now that we all work at so many different resolutions, apps and sites should adapt seamlessly to resizing.
If I were writing this particular app as anything other than an example, I agree that Rails would be overkill. However, I wanted to provide a starting point for Ember/Rails apps that are much more complex. For instance, I wanted to illustrate use of the ember-rails gem, structuring ember files in the asset pipeline, merging handlebars templates in ERB, etc.
I wanted to write out the explicit `return` form of the handler to emphasize that returning a promise in an Orbit event handler has significance. It delays resolution of the event, thereby allowing listeners to participate in that resolution.
Perhaps it was unnecessary for me to _also_ include the implicit return form in that example. However, that's the way I would normally write this function, and I'd like to present "best practices" and show how concise the code is typically.