README.md in jsonapi-serializers-0.1.2 vs README.md in jsonapi-serializers-0.2.0
- old
+ new
@@ -1,14 +1,13 @@
# JSONAPI::Serializers
[](https://travis-ci.org/fotinakis/jsonapi-serializers)
[](http://badge.fury.io/rb/jsonapi-serializers)
-
JSONAPI::Serializers is a simple library for serializing Ruby objects and their relationships into the [JSON:API format](http://jsonapi.org/format/).
-As of writing, the JSON:API spec is approaching v1 and still undergoing changes. This library supports RC3+ and aims to keep up with the continuing development changes.
+This library is up-to-date with the finalized v1 JSON API spec.
* [Features](#features)
* [Installation](#installation)
* [Usage](#usage)
* [Define a serializer](#define-a-serializer)
@@ -51,11 +50,11 @@
```ruby
require 'jsonapi-serializers'
class PostSerializer
include JSONAPI::Serializer
-
+
attribute :title
attribute :content
end
```
@@ -278,21 +277,25 @@
"links": {
"self": "/posts/1"
},
"relationships": {
"author": {
- "self": "/posts/1/links/author",
- "related": "/posts/1/author",
- "linkage": {
+ "links": {
+ "self": "/posts/1/links/author",
+ "related": "/posts/1/author"
+ },
+ "data": {
"type": "users",
"id": "1"
}
},
"comments": {
- "self": "/posts/1/links/comments",
- "related": "/posts/1/comments",
- "linkage": [
+ "links": {
+ "self": "/posts/1/links/comments",
+ "related": "/posts/1/comments"
+ },
+ "data": [
{
"type": "comments",
"id": "1"
}
]
@@ -320,20 +323,24 @@
"links": {
"self": "/comments/1"
},
"relationships": {
"user": {
- "self": "/comments/1/links/user",
- "related": "/comments/1/user",
- "linkage": {
+ "links": {
+ "self": "/comments/1/links/user",
+ "related": "/comments/1/user"
+ },
+ "data": {
"type": "users",
"id": "2"
}
},
"post": {
- "self": "/comments/1/links/post",
- "related": "/comments/1/post"
+ "links": {
+ "self": "/comments/1/links/post",
+ "related": "/comments/1/post"
+ }
}
}
},
{
"id": "2",
@@ -351,17 +358,17 @@
```
Notice a few things:
* The [primary data](http://jsonapi.org/format/#document-structure-top-level) relationships now include "linkage" information for each relationship that was included.
* The related objects themselves are loaded in the top-level `included` member.
-* The related objects _also_ include "linkage" information when a deeper relationship is also present in the compound document. This is a very powerful feature of the JSON:API spec, and allows you to deeply link complicated relationships all in the same document and in a single HTTP response. JSONAPI::Serializers automatically includes the correct linkage information for whatever `include` paths you specify. This conforms to this part of the spec:
-
+* The related objects _also_ include "linkage" data when a deeper relationship is also present in the compound document. This is a very powerful feature of the JSON:API spec, and allows you to deeply link complicated relationships all in the same document and in a single HTTP response. JSONAPI::Serializers automatically includes the correct linkage data for whatever `include` paths you specify. This conforms to this part of the spec:
+
> Note: Full linkage ensures that included resources are related to either the primary data (which could be resource objects or resource identifier objects) or to each other.
- > [JSON:API Compound Documents](http://jsonapi.org/format/#document-structure-compound-documents)
+ > [JSON:API Compound Documents](http://jsonapi.org/format/#document-compound-documents)
#### Relationship path handling
-
+
The `include` param also accepts a string of [relationship paths](http://jsonapi.org/format/#fetching-includes), ie. `include: 'author,comments,comments.user'` so you can pass an `?include` query param directly through to the serialize method. Be aware that letting users pass arbitrary relationship paths might introduce security issues depending on your authorization setup, where a user could `include` a relationship they might not be authorized to see directly. Be aware of what you allow API users to include.
## Rails example
```ruby
@@ -423,12 +430,18 @@
* Support for passing `context` through to serializers is partially complete, but needs more work.
* Support for a `serializer_class` attribute on objects that overrides serializer discovery, would love a PR contribution for this.
* Support for the `fields` spec is planned, would love a PR contribution for this.
* Support for pagination/sorting is unlikely to be supported because it would likely involve coupling to ActiveRecord, but please open an issue if you have ideas of how to support this generically.
+## Release notes
+
+* v0.2.0: Initial release with support for the final v1 JSON API spec.
+
## Contributing
1. Fork it ( https://github.com/fotinakis/jsonapi-serializers/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
+
+Throw a ★ on it! :)