jsonapi-serializer
Version:
A Node.js framework agnostic library for serializing your data to JSON API
203 lines (178 loc) • 4.42 kB
Markdown
# JSON API Serializer
[](https://travis-ci.org/SeyZ/jsonapi-serializer)
A Node.js framework agnostic library for serializing your data to [JSON
API](http://jsonapi.org) (1.0 compliant).
## Installation
`$ npm install jsonapi-serializer`
## Documentation
**JSONAPISerializer(type, data, opts)** serializes the *data* (can be an object or an array) following the rules defined in *opts*.
- type: The resource type.
- data: An object to serialize.
- opts
- *attributes*: An array of attributes to show. You can define an attribute as an option if you want to define some relationships (included or not).
- *ref*: If present, it's considered as a [compount document](http://jsonapi.org/format/#document-compound-documents).
- *attributes*: An array of attributes to show.
- *links*: An object that describes the links. Values can be *string* or a *function* (see examples below)
## Example
### Simple usage
```
var JSONAPISerializer = require('jsonapi-serializer');
new JSONAPISerializer('users', data, {
links: { self: 'http://localhost:3000/api/users' },
attributes: ['firstName', 'lastName']
}).then(function (users) {
// `users` here are JSON API compliant.
});
```
The result will be something like:
```
{
"links": {
"self": "http://localhost:3000/api/users"
},
"data": [{
"type": "users",
"id": "1",
"attributes": {
"first-name": "Sandro",
"last-name": "Munda"
}
}, {
"type": "users",
"id": "2",
"attributes": {
"first-name": "John",
"last-name": "Doe"
},
}]
}
```
### Nested resource
```
var JSONAPISerializer = require('jsonapi-serializer');
new JSONAPISerializer('users', data, {
links: { self: 'http://localhost:3000/api/users' },
attributes: ['firstName', 'lastName', 'address'],
address: {
attributes: ['addressLine1', 'zipCode', 'city']
}
}).then(function (users) {
// `users` here are JSON API compliant.
});
```
The result will be something like:
```
{
"links": {
"self": "http://localhost:3000/api/users"
},
"data": [{
"type": "users",
"id": "1",
"attributes": {
"first-name": "Sandro",
"last-name": "Munda",
"address": {
"address-line1": "630 Central Avenue",
"zip-code": 24012,
"city": "Roanoke"
}
}
}, {
"type": "users",
"id": "2",
"attributes": {
"first-name": "John",
"last-name": "Doe",
"address": {
"address-line1": "400 State Street",
"zip-code": 33702,
"city": "Saint Petersburg"
}
}
}]
}
```
### Compount document
```
var JSONAPISerializer = require('jsonapi-serializer');
new JSONAPISerializer('users', data, {
links: { self: 'http://localhost:3000/api/users' },
attributes: ['firstName', 'lastName', 'books'],
books: {
ref: '_id',
attributes: ['title', 'isbn'],
links: {
self: 'http://example.com/books/1/relationships/author',
related: function (book) {
return 'http://example.com/posts/' + post.id + '/author';
}
}
}
}).then(function (users) {
// `users` here are JSON API compliant.
});
```
The result will be something like:
```
{
"links": {
"self": "http://localhost:3000/api/users"
},
"data": [{
"type": "users",
"id": "1",
"attributes": {
"first-name": "Sandro",
"last-name": "Munda"
},
"relationships": {
"books": {
"data": [
{ "type": "books", "id": "1" },
{ "type": "books", "id": "2" }
]
}
}
}, {
"type": "users",
"id": "2",
"attributes": {
"first-name": "John",
"last-name": "Doe"
},
"relationships": {
"books": {
"data": [
{ "type": "books", "id": "1" },
{ "type": "books", "id": "2" }
]
}
}
}],
"included": [{
"type": "books",
"id": "1",
"attributes": {
"title": "La Vida Estilista",
"isbn": "9992266589"
}
}, {
"type": "books",
"id": "2",
"attributes": {
"title": "La Maria Cebra",
"isbn": "9992264446"
}
}, {
"type": "books",
"id": "3",
"attributes": {
"title": "El Salero Cangrejo",
"isbn": "9992209739"
}
}]
}
```
# License
[MIT](https://github.com/SeyZ/jsonapi-serializer/blob/master/LICENSE)