-
Notifications
You must be signed in to change notification settings - Fork 0
/
links.html
executable file
·163 lines (159 loc) · 8.33 KB
/
links.html
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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<html>
<head>
<meta charset="UTF-8">
<title>Sail - Simple Api Interaction Language -Links</title>
<meta name="description" content="Sail is a hypermedia language for APIs">
<meta name="keywords" content="Hypermedia,API,JSON">
<link rel="stylesheet" type="text/css" href="resources/style.css">
</head>
<body>
<header>
<div class="header">
<a href="./index.html#links"> Home </a>
</div>
</header>
<section class="summary">
<h2>Links</h2>
<p>Links have a very simple structure where the rel and href field are required. The rel field is for locating the link in order to follow it. All links must be in a <strong>#links</strong> section. Each field of this section is the rel value of the link, so links can be located directly, but also the rel value is specified in the link as in some scenarios, it is useful to access links as an array. The href fields contains the mechanism for getting the related information. This mechanism could trigger a request to a backend or it could be an expression that must be executed in the client side upon the response.</p>
</section>
<section class="summary">
<div class="siblings json">
<pre>
<span class="field">"#links"</span>: {
<span class="field">"reviews"</span>: {
<span class="field">"href"</span>:<span class="string">"http://api.com/products/1/reviews"</span>,
<span class="field">"rel"</span>:<span class="string">"reviews"</span>
}
}
</pre>
<pre>
GET http://api.com/products/1/reviews
</pre>
<div>
</section>
<section class="summary">
<h2>Links anywhere</h2>
<p>Links can be specified at any part of the response. That means <strong>#links</strong> section can be located anywhere as many times as need it, as long as it is not repeated more than once at the same level. </p>
<div class="siblings json">
<pre>
{
<span class="field">"id"</span>: <span class="string">"1"</span>,
<span class="field">"name"</span>: <span class="string">"Great product"</span>,
<span class="field">"manufacturer"</span>: {
<span class="field">"name"</span>: <span class="string">"The manufacturer"</span>,
<span class="field">"#links"</span>: {
<span class="field">"detail"</span>: {
<span class="field">"href"</span>:<span class="string">"http://api.com/manufacturers/A"</span>,
<span class="field">"rel"</span>:<span class="string">"detail"</span>
}
}
},
<span class="field">"#links"</span>: {
<span class="field">"reviews"</span>: {
<span class="field">"href"</span>:<span class="string">"http://api.com/products/1/reviews"</span>,
<span class="field">"rel"</span>:<span class="string">"reviews"</span>
},
<span class="field">"similar"</span>: {
<span class="field">"href"</span>:<span class="string">"http://api.com/products?similar=1"</span>,
<span class="field">"rel"</span>:<span class="string">"similar"</span>
}
}
}
</pre>
</div>
</section>
<section class="summary">
<h2>Client side links</h2>
<p>This kind of links are used to connect data that is in the same response but located at different places. The most common use of this links is for avoiding the repetition of data in the response.</p>
<p> Let say we have a list of products and for performances purposes (avoid extra requests to the backend) the manufacturers information is included in the response. As a manufacturer can be repeated through the products, each manufacturer is included once at some location of the response. Then a link to the specific location is incorporated in each product:</p>
<div class="siblings json">
<pre>
{
<span class="field">"items"</span>: [
{
<span class="field">"id"</span>:<span class="string">"1"</span>,
<span class="field">"name"</span>:<span class="string">"Great product"</span>,
<span class="field">"#links"</span>: {
<span class="field">"manufacturer"</span>: {
<span class="field">"href"</span>:<span class="string">"sailpath://$.manufacturers.a"</span>,
<span class="field">"rel"</span>:<span class="string">"manufacturer"</span>
}
}
},
{
<span class="field">"id"</span>:<span class="string">"2"</span>,
<span class="field">"name"</span>:<span class="string">"Another great product"</span>,
<span class="field">"#links"</span>: {
<span class="field">"manufacturer"</span>: {
<span class="field">"href"</span>:<span class="string">"sailpath://$.manufacturers.b"</span>,
<span class="field">"rel"</span>:<span class="string">"manufacturer"</span>
}
}
},
{
<span class="field">"id"</span>:<span class="string">"3"</span>,
<span class="field">"name"</span>:<span class="string">"A third great product"</span>,
<span class="field">"#links"</span>: {
<span class="field">"manufacturer"</span>: {
<span class="field">"href"</span>:<span class="string">"sailpath://$.manufacturers.a"</span>,
<span class="field">"rel"</span>:<span class="string">"manufacturer"</span>
}
}
}
],
<span class="field">"manufacturers"</span>: {
<span class="field">"a"</span>:{},
<span class="field">"b"</span>:{}
}
}
</pre>
</div>
<p>In the example above, <strong>sailpath</strong> is used, which is an extension of jsonpath, but the idea is that any local mechanism can be used. Here the advantages of using client side links:</p>
<ul>
<li>The client doesn't need to implement the "join" of information, as the underlying Sail library takes care of it, leading to less code to test and maintain.</li>
<li>The client is not couple to the structure, this means, if for some reason the manufacturers information changes its location in the response or, though a bit unlikely, it is moved to the backend, the client wont break as it still remains following the link.</li>
</ul>
</section>
<section class="summary">
<h2>Other fields</h2>
<p>There are other optional fields that can be used in a link:</p>
<ul>
<li><strong>title</strong>: is the link's title and can be used for publishing I18N texts, asociated to the link, that the client can use.</li>
<li><strong>type</strong>: indicates the media type of the targeted resource.</li>
<li><strong>data-{name}</strong>: it alows to specify any simple value asociated to the link. A sort of metadata associated to the resource in the other side of the link.</li>
</ul>
<div class="siblings json">
<pre>
<span class="field">"#links"</span>: {
<span class="field">"similar"</span>: {
<span class="field">"href"</span>:<span class="string">"http://api.com/products?similar=1"</span>,
<span class="field">"rel"</span>:<span class="string">"similar"</span>
<span class="field">"type"</span>:<span class="string">"aplication/vnd.sail+json"</span><span class="comment">//The media type of the resource</span>
<span class="field">"title"</span>:<span class="string">"Similar products you might be interested"</span><span class="comment">//I18N text</span>
<span class="field">"data-count"</span>:<span class="value">20</span><span class="comment">//How many items there are</span>
}
}
</pre>
</div>
</section>
<section class="summary">
<h2>Links grouping</h2>
<p>There are scenarios where a response can include a lot of links, where some of them are some how related. Sail provides a mechanism to group links so their access is more easy. Groups can be specified using, of course, a <strong>#</strong> combined with <strong>#links</strong>, for example <strong>#links#group</strong>. The most common case is for a response that represents a list, where links for faceting (filtering), sorting and paging are provided.</p>
<div class="siblings json">
<pre>
{
<span class="field">"#links#facets"</span>: {
<span class="comment">//Links for faceting the list</span>
},
<span class="field">"#links#sorts"</span>: {
<span class="comment">//Links for sorting the list</span>
},
<span class="field">"#links#pages"</span>: {
<span class="comment">//Links for paging the list</span>
}
}
</pre>
</div>
</section>
</body>
</html>