Skip to content

Commit

Permalink
Update the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@SeyZ
SeyZ committed Feb 26, 2016
1 parent 5d4bc40 commit 9c7689e
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 226 deletions.
252 changes: 40 additions & 212 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,60 +9,55 @@ API](http://jsonapi.org) (1.0 compliant).

## Documentation

**JSONAPISerializer(type, data, opts)** serializes the *data* (can be an object or an array) following the rules defined in *opts*.
### Serialization

- 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 relationships.
- *included*: Consider the relationships as [compound document](http://jsonapi.org/format/#document-compound-documents). Default: true.
- *attributes*: An array of attributes to show.
- *topLevelLinks*: An object that describes the top-level links. Values can be *string* or a *function* (see examples below)
- *dataLinks*: An object that describes the links inside data. Values can be *string* or a *function* (see examples below)
- *relationshipLinks*: An object that describes the links inside relationships. Values can be *string* or a *function* (see examples below)
- *relationshipMeta*: An object that describes the meta inside relationships. Values can be *string* or a *function* (see examples below)
- *ignoreRelationshipData*: Do not include the `data` key inside the relationship. Default: false.
- *keyForAttribute*: A function or string to customize attributes. Functions are passed the attribute as a single argument and expect a string to be returned. Strings are aliases for inbuilt functions for common case conversions. Options include:
- dash-case (default)
- lisp-case
- spinal-case
- kebab-case
- underscore_case
- snake_case
- CamelCase
- camelCase
- *pluralizeType*: A boolean to indicate if the type must be pluralized or not. Default: true.
- *typeForAttribute*: A function that maps the attribute (passed as an argument) to the type you want to override. Option *pluralizeType* ignored if set.
- *meta*: An object to include non-standard meta-information.
var JSONAPISerializer = require('jsonapi-serializer').Serializer;
JSONAPISerializer(type, opts).serialize(data);

## Examples
The function `JSONAPISerializer` takes two arguments:

- `type`: The resource type.
- `opts`: The serialization options.

Calling the `serialize` method on the returned object will serialize your `data` (object or array) to a compliant JSONAPI document.


**Available serialization option (`opts` argument)**

- *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 relationships.
- *included*: Consider the relationships as [compound document](http://jsonapi.org/format/#document-compound-documents). Default: true.
- *attributes*: An array of attributes to show.
- *topLevelLinks*: An object that describes the top-level links. Values can be *string* or a *function* (see examples below)
- *dataLinks*: An object that describes the links inside data. Values can be *string* or a *function* (see examples below)
- *relationshipLinks*: An object that describes the links inside relationships. Values can be *string* or a *function* (see examples below)
- *relationshipMeta*: An object that describes the meta inside relationships. Values can be *string* or a *function* (see examples below)
- *ignoreRelationshipData*: Do not include the `data` key inside the relationship. Default: false.
- *keyForAttribute*: A function or string to customize attributes. Functions are passed the attribute as a single argument and expect a string to be returned. Strings are aliases for inbuilt functions for common case conversions. Options include: `dash-case` (default), `lisp-case`, `spinal-case`, `kebab-case`, `underscore_case`, `snake_case`, `camelCase`, `CamelCase`.
- *pluralizeType*: A boolean to indicate if the type must be pluralized or not. Default: true.
- *typeForAttribute*: A function that maps the attribute (passed as an argument) to the type you want to override. Option *pluralizeType* ignored if set.
- *meta*: An object to include non-standard meta-information.

**Examples**

- [Express example](https://github.com/SeyZ/jsonapi-serializer/tree/master/examples/express)
- [Simple](#simple-usage)
- [Nested resource](#nested-resource)
- [Compound document](#compound-document)
- [Simple usage](#simple-usage)
- [More example](https://github.com/SeyZ/jsonapi-serializer/blob/master/test/serializer.js)

<a name="simple-usage"/>
### Simple usage
<a name="simple-usage"></a>
Simple usage:

```javascript
// Sample data object
var data = [{
id: 1,
firstName: 'Sandro',
lastName: 'Munda'
},{
id: 2,
firstName: 'John',
lastName: 'Doe'
}];
var data = [
{ id: 1, firstName: 'Sandro', lastName: 'Munda' },
{ id: 2, firstName: 'John', lastName: 'Doe' }
];
```

```javascript
var JSONAPISerializer = require('jsonapi-serializer');
var JSONAPISerializer = require('jsonapi-serializer').Serializer;

var users =new JSONAPISerializer('users', data, {
var UserSerializer = new JSONAPISerializer('users', {
topLevelLinks: { self: 'http://localhost:3000/api/users' },
dataLinks: {
self: function (user) {
Expand All @@ -72,6 +67,8 @@ var users =new JSONAPISerializer('users', data, {
attributes: ['firstName', 'lastName']
});

var users = UserSerializer.serialize(data);

// `users` here are JSON API compliant.
```

Expand Down Expand Up @@ -102,175 +99,6 @@ The result will be something like:
}
```

<a name="nested-resource"/>
### Nested resource
```javascript
var JSONAPISerializer = require('jsonapi-serializer');

var users = new JSONAPISerializer('users', data, {
topLevelLinks: { self: 'http://localhost:3000/api/users' },
attributes: ['firstName', 'lastName', 'address'],
address: {
attributes: ['addressLine1', 'zipCode', 'city']
}
});

// `users` here are JSON API compliant.
```

The result will be something like:

```javascript
{
"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"
}
}
}]
}
```

<a name="compound-document"/>
### Compound document

```javascript
var JSONAPISerializer = require('jsonapi-serializer');

var users = new JSONAPISerializer('users', data, {
topLevelLinks: { self: 'http://localhost:3000/api/users' },
attributes: ['firstName', 'lastName', 'books'],
books: {
ref: '_id',
attributes: ['title', 'isbn'],
relationshipLinks: {
"self": "http://example.com/relationships/books",
"related": "http://example.com/books"
},
relationshipMeta: {
count: function(user, book) {
return user.books.length;
},
},
includedLinks: {
self: function (dataSet, book) {
return 'http://example.com/books/' + book.id;
}
}
}
});

// `users` here are JSON API compliant.
```

The result will be something like:

```javascript
{
"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" }
],
"links": {
"self": "http://example.com/relationships/books",
"related": "http://example.com/books"
},
"meta": {
"count": 2
}
}
}
}, {
"type": "users",
"id": "2",
"attributes": {
"first-name": "John",
"last-name": "Doe"
},
"relationships": {
"books": {
"data": [
{ "type": "books", "id": "3" }
],
"links": {
"self": "http://example.com/relationships/books",
"related": "http://example.com/books"
},
"meta": {
"count": 1
}
}
}
}],
"included": [{
"type": "books",
"id": "1",
"attributes": {
"title": "La Vida Estilista",
"isbn": "9992266589"
},
"links": {
"self": "http://example.com/books/1"
}
}, {
"type": "books",
"id": "2",
"attributes": {
"title": "La Maria Cebra",
"isbn": "9992264446"
},
"links": {
"self": "http://example.com/books/2"
}
}, {
"type": "books",
"id": "3",
"attributes": {
"title": "El Salero Cangrejo",
"isbn": "9992209739"
},
"links": {
"self": "http://example.com/books/3"
}
}]
}
```


# License

[MIT](https://github.com/SeyZ/jsonapi-serializer/blob/master/LICENSE)
4 changes: 2 additions & 2 deletions examples/express/routes/users.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ router.get('/', function (req, res) {
password: 'ultrasecret'
}];

var json = new UserSerializer(users).serialize();
res.send(json);
var jsonapi = UserSerializer.serialize(users);
res.send(jsonapi);
});

module.exports = router;
16 changes: 4 additions & 12 deletions examples/express/serializers/user.js
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,6 @@
'use strict';
var JSONAPISerializer = require('jsonapi-serializer');
var JSONAPISerializer = require('jsonapi-serializer').Serializer;

function UserSerializer(user) {

this.serialize = function () {
return new JSONAPISerializer('users', user, {
attributes: ['firstName', 'lastName'],
});
};

}

module.exports = UserSerializer;
module.exports = new JSONAPISerializer('users', {
attributes: ['firstName', 'lastName']
});

0 comments on commit 9c7689e

Please sign in to comment.