Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 296 lines (176 sloc) 6.979 kb
9d0d0bc @franckcuny initial import
franckcuny authored
1 =encoding utf-8
2
3 =head1 NAME
4
8890991 @daxim spelling
daxim authored
5 Spore (B<S>pecifications to a B<Po>rtable B<R>EST B<E>nvironment) Description Implementation
9d0d0bc @franckcuny initial import
franckcuny authored
6
7 =head1 ABSTRACT
8
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description docume...
daxim authored
9 Spore is a specification for describing HTTP APIs which happen to suffice some
10 constraints laid out by the REST architectural style. It can be parsed and used
8890991 @daxim spelling
daxim authored
11 automatically by client implementations to communicate with the described API.
9d0d0bc @franckcuny initial import
franckcuny authored
12
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description docume...
daxim authored
13 This document describes how to write the description for such an API in
9d0d0bc @franckcuny initial import
franckcuny authored
14 order to be used with a SPORE Client Implementation.
15
16 =head1 TERMINOLOGY
17
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
18 =head2 API
9d0d0bc @franckcuny initial import
franckcuny authored
19
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description docume...
daxim authored
20 An I<API> is the interface to an application that can exchange data with client
8890991 @daxim spelling
daxim authored
21 applications over HTTP/HTTPS. It presents one or more method endpoints which
22 accept HTTP requests with varying headers, parameters and body content to
9d0d0bc @franckcuny initial import
franckcuny authored
23 perform specific operations.
24
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
25 =head2 Client Implementation
9d0d0bc @franckcuny initial import
franckcuny authored
26
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
27 A I<Client Implementation> is a library targeting a specific system or
9d0d0bc @franckcuny initial import
franckcuny authored
28 language. It can use I<Descriptions files> to create programmatic interfaces
29 usable in applications.
30
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
31 =head2 Description File
9d0d0bc @franckcuny initial import
franckcuny authored
32
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
33 A I<Description File> is a file in JSON format describing an I<API> (see
9d0d0bc @franckcuny initial import
franckcuny authored
34 specification). It can directly be used by a I<Client implementation> to
35 create a programmatic interface in the target system.
36
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
37 =head2 Payload
38
39 The I<Payload> is the data sent in the body of a POST or PUT request.
40 The Payload is unrelated to method parameters defined herein.
41
42 =head2 Format
43
44 The I<Format> is the kind of data serialization used for the Payload.
9d0d0bc @franckcuny initial import
franckcuny authored
45
46 =head1 API DESCRIPTION
47
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
48 An API should provide a description file, in JSON format, that conforms with this description.
9d0d0bc @franckcuny initial import
franckcuny authored
49
50 =head2 GENERIC DESCRIPTION
51
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
52 This part describes the overall API and provides some default values for the
53 individual method descriptions.
9d0d0bc @franckcuny initial import
franckcuny authored
54
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
55 =head3 name
9d0d0bc @franckcuny initial import
franckcuny authored
56
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
57 A required simple name to describe the specification
9d0d0bc @franckcuny initial import
franckcuny authored
58
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
59 "name" : "CouchDB"
9d0d0bc @franckcuny initial import
franckcuny authored
60
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
61 =head3 authority
9d0d0bc @franckcuny initial import
franckcuny authored
62
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
63 An optional authority of the description
9d0d0bc @franckcuny initial import
franckcuny authored
64
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
65 "authority" : "GITHUB:franckcuny"
9d0d0bc @franckcuny initial import
franckcuny authored
66
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
67 =head3 base_url
9d0d0bc @franckcuny initial import
franckcuny authored
68
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
69 An optional base URL for the API
9d0d0bc @franckcuny initial import
franckcuny authored
70
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
71 "base_url" : "http://api.twitter.com/1/"
9d0d0bc @franckcuny initial import
franckcuny authored
72
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
73 =head3 formats
9d0d0bc @franckcuny initial import
franckcuny authored
74
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
75 A list of supported formats
9d0d0bc @franckcuny initial import
franckcuny authored
76
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
77 "formats" : [
78 "json"
79 "xml"
80 ]
9d0d0bc @franckcuny initial import
franckcuny authored
81
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
82 =head3 version
9d0d0bc @franckcuny initial import
franckcuny authored
83
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
84 A mandatory version number of the SPORE description of the API, expressed as a string
9d0d0bc @franckcuny initial import
franckcuny authored
85
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
86 "version" : "0.1"
9d0d0bc @franckcuny initial import
franckcuny authored
87
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
88 =head3 authentication
9d0d0bc @franckcuny initial import
franckcuny authored
89
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
90 An optional boolean to specify if this API requires authentication for all the methods
9d0d0bc @franckcuny initial import
franckcuny authored
91
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
92 "authentication" : true
9d0d0bc @franckcuny initial import
franckcuny authored
93
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
94 The default is false.
9d0d0bc @franckcuny initial import
franckcuny authored
95
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
96 =head3 methods
9d0d0bc @franckcuny initial import
franckcuny authored
97
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
98 A mandatory hash of method names and specifications.
99 See L</METHOD DESCRIPTION>.
9d0d0bc @franckcuny initial import
franckcuny authored
100
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
101 "methods" : { ... }
9d0d0bc @franckcuny initial import
franckcuny authored
102
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
103 The C<methods> hash B<MUST> contain at least one method.
9d0d0bc @franckcuny initial import
franckcuny authored
104
105 =head2 METHOD DESCRIPTION
106
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
107 A method must have a name, which is the key in the L</methods> hash
9d0d0bc @franckcuny initial import
franckcuny authored
108
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
109 "methods" : {
110 "public_timeline" : { ... }
111 }
9d0d0bc @franckcuny initial import
franckcuny authored
112
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
113 =head3 method
114
115 The mandatory C<method> attribute specifies the HTTP method to use for this call
9d0d0bc @franckcuny initial import
franckcuny authored
116
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
117 "method" : "GET"
9d0d0bc @franckcuny initial import
franckcuny authored
118
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
119 =head3 path
9d0d0bc @franckcuny initial import
franckcuny authored
120
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
121 The mandatory C<path> attribute specifies the URI path for this method.
9d0d0bc @franckcuny initial import
franckcuny authored
122
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
123 "path" : "/login"
9d0d0bc @franckcuny initial import
franckcuny authored
124
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
125 The path can contain I<placeholders>. A placeholder
9d0d0bc @franckcuny initial import
franckcuny authored
126 B<MUST> begin with a <:>:
127
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
128 "path" : "/statuses/public_timeline.:format"
9d0d0bc @franckcuny initial import
franckcuny authored
129
8890991 @daxim spelling
daxim authored
130 XXX How can non-placeholder :foo's be included in the path? i.e. is there an escape mechanism?
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
131 XXX What happens in this example if 'format' isn't listed in params/required?
8890991 @daxim spelling
daxim authored
132 XXX What happens if a parameter needs to be followed by a word character? i.e. can something like :{format}foo be used?
9d0d0bc @franckcuny initial import
franckcuny authored
133
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
134 =head3 optional_params
9d0d0bc @franckcuny initial import
franckcuny authored
135
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
136 An optional list of optional parameters (contrast with L</required_params>).
137 This list will be used to replace value in placeholders, and if not used in the
138 path, will be added to the query part of the request URL.
9d0d0bc @franckcuny initial import
franckcuny authored
139
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
140 "optional_params" : [
141 "trim_user",
142 "include_entities"
143 ]
9d0d0bc @franckcuny initial import
franckcuny authored
144
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
145 =head3 required_params
9d0d0bc @franckcuny initial import
franckcuny authored
146
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
147 An optional list of required parameters (contrast with L</optional_params>).
148 This list will be used to replace value in placeholders and, if not used in the
149 path, will be added to the query part of the request URL.
9d0d0bc @franckcuny initial import
franckcuny authored
150
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
151 Parameters that are required B<MUST NOT> be repeated in the B<optional_params> field
9d0d0bc @franckcuny initial import
franckcuny authored
152
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
153 "required" : [
154 "format"
155 ]
9d0d0bc @franckcuny initial import
franckcuny authored
156
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
157 =head3 expected_status
9d0d0bc @franckcuny initial import
franckcuny authored
158
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
159 An optional list of accepted HTTP status codes for this method
9d0d0bc @franckcuny initial import
franckcuny authored
160
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
161 "expected" : [
162 200,
163 204
164 ]
165
166 If C<expected> is specified then an exception will be thrown if the response
167 status is not in the list. If C<expected> is not specified then an exception
8890991 @daxim spelling
daxim authored
168 will be thrown if the response status is not in the range 200 through 299.
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
169
170 XXX a global default_expected could be handy.
171
172 =head3 description
173
174 An optional simple description for the method. This should not be considered as
9d0d0bc @franckcuny initial import
franckcuny authored
175 documentation.
176
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
177 "description" : "Returns the 20 most recent statuses, including retweets if they exist, from non-protected users"
9d0d0bc @franckcuny initial import
franckcuny authored
178
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
179 =head3 authentication
9d0d0bc @franckcuny initial import
franckcuny authored
180
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
181 An optional boolean to specify if this method requires authentication
9d0d0bc @franckcuny initial import
franckcuny authored
182
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
183 "authentication" : false
a917f3e @ngrunwald - transformed numbers in booleans
ngrunwald authored
184
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
185 =head3 base_url
9d0d0bc @franckcuny initial import
franckcuny authored
186
8890991 @daxim spelling
daxim authored
187 An optional base URL for this method, if different to the default specified above.
9d0d0bc @franckcuny initial import
franckcuny authored
188
b92a4af @franckcuny update specification for the description
franckcuny authored
189 base_url: http://api.twitter.com/1/
9d0d0bc @franckcuny initial import
franckcuny authored
190
8890991 @daxim spelling
daxim authored
191 XXX might be nice to be able to express this as a relative URL (relative to api_base_url) That could be handled at build time.
9d0d0bc @franckcuny initial import
franckcuny authored
192
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
193 =head3 formats
9d0d0bc @franckcuny initial import
franckcuny authored
194
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
195 An optional list of supported formats
9d0d0bc @franckcuny initial import
franckcuny authored
196
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
197 "format" : [
198 "json",
199 "xml"
200 ]
9d0d0bc @franckcuny initial import
franckcuny authored
201
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
202 =head3 documentation
9d0d0bc @franckcuny initial import
franckcuny authored
203
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
204 Optional detailed documentation for the given method
9d0d0bc @franckcuny initial import
franckcuny authored
205
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
206 "documentation" : "The public timeline is cached for 60 seconds. Requesting more frequently than that will not return any more data, and will count against your rate limit usage."
9d0d0bc @franckcuny initial import
franckcuny authored
207
208 =head3 SAMPLE
209
210 A description for the twitter API (only the API description part and the first method):
211
212 {
b92a4af @franckcuny update specification for the description
franckcuny authored
213 "base_url" : "http://api.twitter.com/1",
9d0d0bc @franckcuny initial import
franckcuny authored
214 "version" : "0.1",
215 "methods" : {
216 "public_timeline" : {
b92a4af @franckcuny update specification for the description
franckcuny authored
217 "optional_params" : [
9d0d0bc @franckcuny initial import
franckcuny authored
218 "trim_user",
219 "include_entities"
220 ],
b92a4af @franckcuny update specification for the description
franckcuny authored
221 "required_params" : [
9d0d0bc @franckcuny initial import
franckcuny authored
222 "format"
223 ],
224 "path" : "/statuses/public_timeline.:format",
225 "method" : "GET"
b92a4af @franckcuny update specification for the description
franckcuny authored
226 }
9d0d0bc @franckcuny initial import
franckcuny authored
227 }
228 }
229
230 =head3 CALLS
231
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
232 XXX
9d0d0bc @franckcuny initial import
franckcuny authored
233
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
234 =head1 CHANGES
9d0d0bc @franckcuny initial import
franckcuny authored
235
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
236 =head2 0.1 - 2010.10.xx
9d0d0bc @franckcuny initial import
franckcuny authored
237
238 Initial version.
239
240 =head1 ACKNOWLEDGEMENTS
241
242 Some parts of this specification are adopted from the following specifications.
243
244 =over 4
245
246 =item *
247
248 PSGI Specification L<PSGI|http://search.cpan.org/perldoc?PSGI>
249
250 =item *
251
252 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
253
254 =item *
255
256 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
257
258 =item *
259
260 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
261
262 =back
263
264 I'd like to thank authors of these great documents.
265
266 =head1 AUTHOR
267
268 =over 4
269
270 =item franck cuny
271
272 =item nils grunwald
273
274 =back
275
276 =head1 CONTRIBUTORS
277
278 =over 4
279
280 =item damien "bl0b" leroux
281
b92a4af @franckcuny update specification for the description
franckcuny authored
282 =item François Perrad
283
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exception b...
timbunce authored
284 =item Tim Bunce
285
9d0d0bc @franckcuny initial import
franckcuny authored
286 =back
287
288 =head1 COPYRIGHT AND LICENSE
289
290 Copyright XXX, 2010.
291
2b5b523 @daxim apply licence as stipulated
daxim authored
292 This work is licensed under a L<Creative Commons Attribution-ShareAlike 3.0
293 Unported License|http://creativecommons.org/licenses/by-sa/3.0/>.
9d0d0bc @franckcuny initial import
franckcuny authored
294
295 =cut
Something went wrong with that request. Please try again.