Skip to content
Newer
Older
100644 295 lines (175 sloc) 6.74 KB
9d0d0bc initial import
franck cuny 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 initial import
franck cuny authored
6
7 =head1 ABSTRACT
8
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description doc…
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 initial import
franck cuny authored
12
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description doc…
daxim authored
13 This document describes how to write the description for such an API in
9d0d0bc initial import
franck cuny 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 exceptio…
timbunce authored
18 =head2 API
9d0d0bc initial import
franck cuny authored
19
918b4c7 @daxim REST interfaces by definition cannot have out-of-band description doc…
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 initial import
franck cuny authored
23 perform specific operations.
24
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
25 =head2 Client Implementation
9d0d0bc initial import
franck cuny authored
26
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
27 A I<Client Implementation> is a library targeting a specific system or
9d0d0bc initial import
franck cuny 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 exceptio…
timbunce authored
31 =head2 Description File
9d0d0bc initial import
franck cuny authored
32
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
33 A I<Description File> is a file in JSON format describing an I<API> (see
9d0d0bc initial import
franck cuny 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 exceptio…
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 initial import
franck cuny authored
45
46 =head1 API DESCRIPTION
47
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
48 An API should provide a description file, in JSON format, that conforms with this description.
9d0d0bc initial import
franck cuny authored
49
50 =head2 GENERIC DESCRIPTION
51
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
52 This part describes the overall API and provides some default values for the
53 individual method descriptions.
9d0d0bc initial import
franck cuny authored
54
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
55 =head3 name
9d0d0bc initial import
franck cuny authored
56
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
57 A required simple name to describe the specification
9d0d0bc initial import
franck cuny authored
58
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
59 "name" : "CouchDB"
9d0d0bc initial import
franck cuny authored
60
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
61 =head3 authority
9d0d0bc initial import
franck cuny authored
62
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
63 An optional authority of the description
9d0d0bc initial import
franck cuny authored
64
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
65 "authority" : "GITHUB:franckcuny"
9d0d0bc initial import
franck cuny authored
66
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
67 =head3 base_url
9d0d0bc initial import
franck cuny authored
68
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
69 An optional base URL for the API
9d0d0bc initial import
franck cuny authored
70
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
71 "base_url" : "http://api.twitter.com/1/"
9d0d0bc initial import
franck cuny authored
72
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
73 =head3 formats
9d0d0bc initial import
franck cuny authored
74
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
75 A list of supported formats
9d0d0bc initial import
franck cuny authored
76
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
77 "formats" : [
78 "json"
79 "xml"
80 ]
9d0d0bc initial import
franck cuny authored
81
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
82 =head3 version
9d0d0bc initial import
franck cuny authored
83
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
84 A mandatory version number of the SPORE description of the API, expressed as a string
9d0d0bc initial import
franck cuny authored
85
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
86 "version" : "0.1"
9d0d0bc initial import
franck cuny authored
87
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
88 =head3 authentication
9d0d0bc initial import
franck cuny authored
89
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
90 An optional boolean to specify if this API requires authentication for all the methods
9d0d0bc initial import
franck cuny authored
91
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
92 "authentication" : true
9d0d0bc initial import
franck cuny authored
93
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
94 The default is false.
9d0d0bc initial import
franck cuny authored
95
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
96 =head3 methods
9d0d0bc initial import
franck cuny authored
97
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
98 A mandatory hash of method names and specifications.
99 See L</METHOD DESCRIPTION>.
9d0d0bc initial import
franck cuny authored
100
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
101 "methods" : { ... }
9d0d0bc initial import
franck cuny authored
102
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
103 The C<methods> hash B<MUST> contain at least one method.
9d0d0bc initial import
franck cuny authored
104
105 =head2 METHOD DESCRIPTION
106
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
107 A method must have a name, which is the key in the L</methods> hash
9d0d0bc initial import
franck cuny authored
108
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
109 "methods" : {
110 "public_timeline" : { ... }
111 }
9d0d0bc initial import
franck cuny authored
112
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
113 =head3 method
114
115 The mandatory C<method> attribute specifies the HTTP method to use for this call
9d0d0bc initial import
franck cuny authored
116
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
117 "method" : "GET"
9d0d0bc initial import
franck cuny authored
118
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
119 =head3 path
9d0d0bc initial import
franck cuny authored
120
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
121 The mandatory C<path> attribute specifies the URI path for this method.
9d0d0bc initial import
franck cuny authored
122
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
123 "path" : "/login"
9d0d0bc initial import
franck cuny authored
124
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
125 The path can contain I<placeholders>. A placeholder
9d0d0bc initial import
franck cuny authored
126 B<MUST> begin with a <:>:
127
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
128 "path" : "/statuses/public_timeline.:format"
9d0d0bc initial import
franck cuny 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 exceptio…
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 initial import
franck cuny authored
133
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
134 =head3 optional_params
9d0d0bc initial import
franck cuny authored
135
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
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 initial import
franck cuny authored
139
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
140 "optional_params" : [
141 "trim_user",
142 "include_entities"
143 ]
9d0d0bc initial import
franck cuny authored
144
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
145 =head3 required_params
9d0d0bc initial import
franck cuny authored
146
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
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 initial import
franck cuny authored
150
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
151 Parameters that are required B<MUST NOT> be repeated in the B<optional_params> field
9d0d0bc initial import
franck cuny authored
152
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
153 "required" : [
154 "format"
155 ]
9d0d0bc initial import
franck cuny authored
156
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
157 =head3 expected_status
9d0d0bc initial import
franck cuny authored
158
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
159 An optional list of accepted HTTP status codes for this method
9d0d0bc initial import
franck cuny authored
160
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
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 exceptio…
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 initial import
franck cuny authored
175 documentation.
176
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
177 "description" : "Returns the 20 most recent statuses, including retweets if they exist, from non-protected users"
9d0d0bc initial import
franck cuny authored
178
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
179 =head3 authentication
9d0d0bc initial import
franck cuny authored
180
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
181 An optional boolean to specify if this method requires authentication
9d0d0bc initial import
franck cuny authored
182
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
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 exceptio…
timbunce authored
185 =head3 base_url
9d0d0bc initial import
franck cuny authored
186
8890991 @daxim spelling
daxim authored
187 An optional base URL for this method, if different to the default specified above.
9d0d0bc initial import
franck cuny authored
188
b92a4af update specification for the description
franck cuny authored
189 base_url: http://api.twitter.com/1/
9d0d0bc initial import
franck cuny 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 initial import
franck cuny authored
192
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
193 =head3 formats
9d0d0bc initial import
franck cuny authored
194
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
195 An optional list of supported formats
9d0d0bc initial import
franck cuny authored
196
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
197 "format" : [
198 "json",
199 "xml"
200 ]
9d0d0bc initial import
franck cuny authored
201
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
202 =head3 documentation
9d0d0bc initial import
franck cuny authored
203
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
204 Optional detailed documentation for the given method
9d0d0bc initial import
franck cuny authored
205
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
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 initial import
franck cuny 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 update specification for the description
franck cuny authored
213 "base_url" : "http://api.twitter.com/1",
9d0d0bc initial import
franck cuny authored
214 "version" : "0.1",
215 "methods" : {
216 "public_timeline" : {
b92a4af update specification for the description
franck cuny authored
217 "optional_params" : [
9d0d0bc initial import
franck cuny authored
218 "trim_user",
219 "include_entities"
220 ],
b92a4af update specification for the description
franck cuny authored
221 "required_params" : [
9d0d0bc initial import
franck cuny authored
222 "format"
223 ],
224 "path" : "/statuses/public_timeline.:format",
225 "method" : "GET"
b92a4af update specification for the description
franck cuny authored
226 }
9d0d0bc initial import
franck cuny authored
227 }
228 }
229
230 =head3 CALLS
231
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
232 XXX
9d0d0bc initial import
franck cuny authored
233
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
234 =head1 CHANGES
9d0d0bc initial import
franck cuny authored
235
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
236 =head2 0.1 - 2010.10.xx
9d0d0bc initial import
franck cuny 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 update specification for the description
franck cuny authored
282 =item François Perrad
283
3ad2257 @timbunce Simplify & clarify pod. Use JSON. Flag some issues. Document exceptio…
timbunce authored
284 =item Tim Bunce
285
9d0d0bc initial import
franck cuny authored
286 =back
287
288 =head1 COPYRIGHT AND LICENSE
289
290 Copyright XXX, 2010.
291
292 This document is licensed under the Creative Commons license by-sa.
293
294 =cut
Something went wrong with that request. Please try again.