Skip to content

JSON API v1.0rc1, simplified #237

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 8 commits into from
Jul 5, 2014
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion _includes/status.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Status <a href="#status" id="status" class="headerlink"></a>
## Status <a href="#status" id="status" class="headerlink"></a>

**This document is a work in progress** and will change as implementation work
progresses. See the [Status](/status) page for more information.
6 changes: 3 additions & 3 deletions about/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ layout: page
title: About
---

## Channels <a href="#channels" id="channels" class="headerlink"></a>
## Channels <a href="#channels" id="channels" class="headerlink"></a>

JSON API is:

Expand All @@ -12,7 +12,7 @@ JSON API is:
* _#jsonapi_ channel on [Freenode IRC](http://freenode.net)
* [jsonapi Google group](https://groups.google.com/forum/?fromgroups#!forum/jsonapi)

## Editors <a href="#editors" id="editors" class="headerlink"></a>
## Editors <a href="#editors" id="editors" class="headerlink"></a>

There are two primary editors of this specification:

Expand All @@ -29,7 +29,7 @@ There are two primary editors of this specification:
Steve primarily represents the server side, Yehuda the client side. Both of us
care about both, but we want to make sure to have a champion on either side.

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

JSON API is extracted from the JSON transport implicitly defined by
[Ember](http://emberjs.com/) Data's REST adapter.
Expand Down
24 changes: 12 additions & 12 deletions examples/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,30 @@ API are divided into server- and client-side. The server-side is further
divided by implementation language. If you'd like your project listed, [send a
Pull Request](https://github.com/json-api/json-api).

## Client <a href="#client" id="client" class="headerlink"></a>
## Client <a href="#client" id="client" class="headerlink"></a>

### JavaScript <a href="#client-javascript" id="client-javascript" class="headerlink"></a>
### JavaScript <a href="#client-javascript" id="client-javascript" class="headerlink"></a>

* [ember-data](https://github.com/emberjs/data) is one of the original exemplar
implementations. There is a [custom adapter](https://github.com/daliwali/ember-json-api) to support json-api.

* [backbone-jsonapi](https://github.com/guillaumervls/backbone-jsonapi) is a Backbone adapter for JSON API. Supports fetching Models & Collections from a JSON API source.

### iOS <a href="#client-ios" id="client-ios" class="headerlink"></a>
### iOS <a href="#client-ios" id="client-ios" class="headerlink"></a>

* [jsonapi-ios](https://github.com/joshdholtz/jsonapi-ios) is a library for loading data from a JSON API datasource. Parses JSON API data into models with support for auto-linking of resources and custom model classes.

## Server <a href="#server" id="server" class="headerlink"></a>
## Server <a href="#server" id="server" class="headerlink"></a>

### PHP <a href="#server-php" id="server-php" class="headerlink"></a>
### PHP <a href="#server-php" id="server-php" class="headerlink"></a>

* [FriendsOfSymfony / FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle/issues/452)

### Node.js <a href="#server-node-js" id="server-node-js" class="headerlink"></a>
### Node.js <a href="#server-node-js" id="server-node-js" class="headerlink"></a>

* [Fortune.js](http://fortunejs.com) is a framework built to implement json-api.

### Ruby <a href="#server-ruby" id="server-ruby" class="headerlink"></a>
### Ruby <a href="#server-ruby" id="server-ruby" class="headerlink"></a>

* [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)
is one of the original exemplar implementations, but is slightly out of date at
Expand All @@ -44,22 +44,22 @@ has page describing how to emit conformant JSON.

* [Oat](https://github.com/ismasan/oat#adapters) ships with a JSON API adapter.

### Python <a href="#server-python" id="server-python" class="headerlink"></a>
### Python <a href="#server-python" id="server-python" class="headerlink"></a>

* [Hyp](https://github.com/kalasjocke/hyp) is a library for creating json-api responses.

## Messages <a href="#messages" id="messages" class="headerlink"></a>
## Messages <a href="#messages" id="messages" class="headerlink"></a>

* [RestPack::Serializer provides examples](http://restpack-serializer-sample.herokuapp.com/) which demonstrate sample responses.

## Related Tools <a href="#related-tools" id="related-tools" class="headerlink"></a>
## Related Tools <a href="#related-tools" id="related-tools" class="headerlink"></a>

### Ruby <a href="#related-tools-ruby" id="related-tools-ruby" class="headerlink"></a>
### Ruby <a href="#related-tools-ruby" id="related-tools-ruby" class="headerlink"></a>

* [json-patch](https://github.com/guillec/json-patch) implementation of JSON Patch (rfc6902)

* [hana](https://github.com/tenderlove/hana) implementation of the JSON Patch and JSON pointer spec

### Node.js <a href="#relted-tools-node-js" id="relted-tools-node-js" class="headerlink"></a>
### Node.js <a href="#relted-tools-node-js" id="relted-tools-node-js" class="headerlink"></a>

* [json-patch](https://www.npmjs.org/package/json-patch) implementation of JSON Patch (rfc6902)
4 changes: 2 additions & 2 deletions extending/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Extending

{% include status.md %}

## Extending <a href="#extending" id="extending" class="headerlink"></a>
## Extending <a href="#extending" id="extending" class="headerlink"></a>

If you would like to extend JSON API, you may do so with the profile link
relation, defined in [RFC 6906](http://tools.ietf.org/html/rfc6906). See also
Expand All @@ -23,7 +23,7 @@ extensions) that are associated with the resource representation, in addition
to those defined by the media type and possibly other mechanisms.
```

## Examples <a href="#examples" id="examples" class="headerlink"></a>
## Examples <a href="#examples" id="examples" class="headerlink"></a>

For example, let's say that you want your API to support a different pagination
scheme, such as one based on cursors. You would make some sort of profile page
Expand Down
27 changes: 22 additions & 5 deletions faq/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ layout: page
title: Frequently Asked Questions
---

### Why is JSON API not versioned? <a href="#why-is-json-api-not-versioned" id="why-is-json-api-not-versioned" class="headerlink"></a>
### Why is JSON API not versioned? <a href="#why-is-json-api-not-versioned" id="why-is-json-api-not-versioned" class="headerlink"></a>

Once JSON API is stable, it will always be backwards compatible using a _never
remove, only add_ strategy.
[#46](https://github.com/json-api/json-api/issues/46)

### Why not use the HAL specification? <a href="#why-not-use-the-hal-specification" id="why-not-use-the-hal-specification" class="headerlink"></a>
### Why not use the HAL specification? <a href="#why-not-use-the-hal-specification" id="why-not-use-the-hal-specification" class="headerlink"></a>

There are several reasons:

Expand Down Expand Up @@ -37,7 +37,7 @@ It is extracted from a real-world library already used by a number of projects,
which has informed both the request/response aspects (absent from HAL) and the
interchange format itself.

### How to discover resource possible actions? <a href="#how-to-discover-resource-possible-actions" id="how-to-discover-resource-possible-actions" class="headerlink"></a>
### How to discover resource possible actions? <a href="#how-to-discover-resource-possible-actions" id="how-to-discover-resource-possible-actions" class="headerlink"></a>

You should use the OPTIONS HTTP method to discover what can be done with a
particular resource. The semantics of the methods returned by OPTIONS is defined
Expand All @@ -52,7 +52,7 @@ and capabilities and use the errors response to let users know. This error featu
is still pending to be included in the standard since is still in
[discussion](https://github.com/json-api/json-api/issues/7).

### Is there a JSON Schema describing JSON API? <a href="#is-there-a-json-schema-describing-json-api" id="is-there-a-json-schema-describing-json-api" class="headerlink"></a>
### Is there a JSON Schema describing JSON API? <a href="#is-there-a-json-schema-describing-json-api" id="is-there-a-json-schema-describing-json-api" class="headerlink"></a>

Yes, you can find the JSON Schema definition at
[http://jsonapi.org/schema](http://jsonapi.org/schema). Please note that this
Expand All @@ -61,4 +61,21 @@ against this schema, that does not necessarily mean it is a valid JSON API
document. The schema is provided for a base level sanity check.

You can find more information about the JSON Schema format at
[http://json-schema.org](http://json-schema.org).
[http://json-schema.org](http://json-schema.org).

### Why are resource collections returned as arrays instead of sets keyed by ID?

A JSON array is naturally ordered while sets require metadata to specify order
among members. Therefore, arrays allow for more natural sorting by default or
specified criteria.

In addition, JSON API allows read-only resources to be returned without IDs,
which would of course be incompatible with a set keyed by IDs.

### Why are related resources nested in a `linked` object in a compound document?

Primary resources should be isolated because their order and number is often
significant. It's necessary to separate primary and related resources by more
than type because it's possible that a primary resource may have related
resources of the same type (e.g. the "parents" of a "person"). Nesting related
resources in `linked` prevents this possible conflict.
Loading
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