1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
# jsonapi-renderer
Ruby gem for rendering [JSON API](http://jsonapi.org) documents.
## Status
[](https://badge.fury.io/rb/jsonapi-renderer)
[](http://travis-ci.org/jsonapi-rb/renderer?branch=master)
[](https://codecov.io/gh/jsonapi-rb/renderer)
[](https://gitter.im/jsonapi-rb/Lobby)
## Resources
* Chat: [gitter](http://gitter.im/jsonapi-rb)
* Twitter: [@jsonapirb](http://twitter.com/jsonapirb)
* Docs: [jsonapi-rb.org](http://jsonapi-rb.org)
## Installation
```ruby
# In Gemfile
gem 'jsonapi-renderer'
```
then
```
$ bundle
```
or manually via
```
$ gem install jsonapi-renderer
```
## Usage
First, require the gem:
```ruby
require 'jsonapi/renderer'
```
### Rendering resources
A resource here is any class that implements the following interface:
```ruby
class ResourceInterface
# Returns the type of the resource.
# @return [String]
def jsonapi_type; end
# Returns the id of the resource.
# @return [String]
def jsonapi_id; end
# Returns a hash containing, for each included relationship, an array of the
# resources to be included from that one.
# @param included_relationships [Array<Symbol>] The keys of the relationships
# to be included.
# @return [Hash{Symbol => Array<#ResourceInterface>}]
def jsonapi_related(included_relationships); end
# Returns a JSON API-compliant representation of the resource as a hash.
# @param options [Hash]
# @option fields [Set<Symbol>, Nil] The requested fields, or nil.
# @option include [Set<Symbol>] The requested relationships to
# include (defaults to []).
# @return [Hash]
def as_jsonapi(options = {}); end
end
```
#### Rendering a single resource
```ruby
JSONAPI.render(data: resource,
include: include_string,
fields: fields_hash,
meta: meta_hash,
links: links_hash)
```
This returns a JSON API compliant hash representing the described document.
#### Rendering a collection of resources
```ruby
JSONAPI.render(data: resources,
include: include_string,
fields: fields_hash,
meta: meta_hash,
links: links_hash)
```
This returns a JSON API compliant hash representing the described document.
#### Rendering a relationship
```ruby
JSONAPI.render(data: resource,
relationship: :posts,
include: include_string,
fields: fields_hash,
meta: meta_hash,
links: links_hash)
```
This returns a JSON API compliant hash representing the described document.
### Rendering errors
```ruby
JSONAPI.render_errors(errors: errors,
meta: meta_hash,
links: links_hash)
```
where `errors` is an array of objects implementing the `as_jsonapi` method, that
returns a JSON API-compliant representation of the error.
This returns a JSON API compliant hash representing the described document.
### Caching
The generated JSON fragments can be cached in any cache implementation
supporting the `fetch_multi` method.
When using caching, the serializable resources must implement an
additional `jsonapi_cache_key` method:
```ruby
# Returns a cache key for the resource, parameterized by the `include` and
# `fields` options.
# @param options [Hash]
# @option fields [Set<Symbol>, Nil] The requested fields, or nil.
# @option include [Set<Symbol>] The requested relationships to
# include (defaults to []).
# @return [String]
def jsonapi_cache_key(options = {}); end
```
The cache instance must be passed to the renderer as follows:
```ruby
JSONAPI.render(data: resources,
include: include_string,
fields: fields_hash,
cache: cache_instance)
```
## License
jsonapi-renderer is released under the [MIT License](http://www.opensource.org/licenses/MIT).
|
