Skip to content

Update history #1590

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

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from
Open

Update history #1590

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d47c12
Update history
sandstrom Nov 3, 2021
d6012cb
fixup! Update history
sandstrom Aug 10, 2022
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
41 changes: 20 additions & 21 deletions about/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,25 @@ The following emeritus editors are no longer active:

## <a href="#history" id="history" class="headerlink"></a> History

JSON:API was originally drafted by [Yehuda Katz](http://twitter.com/wycats)
JSON:API was originally drafted by [Yehuda Katz](https://twitter.com/wycats)
in May 2013. This first draft was extracted from the JSON transport
implicitly defined by [Ember](http://emberjs.com/) Data's REST adapter.
implicitly defined by [Ember](https://emberjs.com/) Data's REST adapter.

In general, Ember Data's goal is to eliminate the need for ad-hoc code
per application to communicate with servers that communicate in a
well-defined way.
The goals of the JSON:API specification are to balance:

* A generic media type that can work across a broad set of use cases,
including the generally used relationship types
* Similarity to existing server-side framework practices (and human
readability for debugging)
* Ease of implementation on the server side
* Ease of implementation on the client side
Comment on lines +44 to +49
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not sure if I would phrase the goals like this. It also conflicts, which the marketing statements on the homepage, which focus on

  1. avoid bike-shedding about API design,
  2. efficient caching, and
  3. avoid unnecessary network requests.

If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can be your anti-bikeshedding tool.

By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application.

Clients built around JSON:API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.

Personally I would phrase the goals (looking back) as the following:

  1. Standardize REST API design to
    1. avoid bike-shedding about API design, which is not specific to the business requirements, and
    2. enable development of compatible client- and server-side libraries.
  2. Built on-top of established REST API patterns to enable incremental adoption and a flat learning curve.
  3. Reduce the risk of write conflicts on REST API design level (e.g. PATCH for updating resources and partial updates of to-many relationships using relationship links).
  4. Support advanced use cases like polymorphic relationships.
  5. Allow clients to fetch all needed data in a single request to avoid unnecessary network requests (under-fetching).
  6. Allow clients to request a subset of resource fields to avoid sending unnecessary data over the wire (over-fetching).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sure, I just copied text around. I didn't write any of that.

What you suggest sounds good! I've enabled maintainers to make copies in this fork, so you can make whatever changes you want.


This specification reached a stable version 1.0 on May 29, 2015.

Today there are implementations in a range of languages and frameworks,
both server-side and client-side. But the idea for JSON API was born out of
the Ember project, to eliminate the need for ad-hoc code per application to
communicate with servers that communicate in a well-defined way.

Some servers, like Firebase, Parse and CouchDB already define strict
communication protocols for clients, and were good fits for Ember Data.
Expand All @@ -51,23 +63,10 @@ client code.

The REST Adapter in Ember Data implicitly defined a protocol that
custom servers could implement to get a drop-in client for all of their
resources. [ActiveModel::Serializers][1] is a proof-of-concept library
for Rails that implemented the serialization format expected by Ember
Data.
resources. [Blueprinter][1] is a proof-of-concept library for Rails that
implement the serialization format defined by JSON API.

[1]: https://github.com/rails-api/active_model_serializers
[1]: https://github.com/procore/blueprinter

Record creation, update, and deletion was defined implicitly by the
Ember Data library and was close to conventions already in wide use by
Rails, Django and Node developers.

The goals of the media type are to balance:

* A generic media type that can work across a broad set of use cases,
including the generally used relationship types
* Similarity to existing server-side framework practices (and human
readability for debugging)
* Ease of implementation on the server side
* Ease of implementation on the client side

This specification reached a stable version 1.0 on May 29, 2015.
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