Skip to content
This repository
Newer
Older
100644 279 lines (161 sloc) 5.409 kb
9d0d0bc5 » franckcuny
2010-10-12 initial import
1 =encoding utf-8
2
3 =head1 NAME
4
5 Spore (Specifications to a POrtable Rest Environment) Description Implementation
6
7 =head1 ABSTRACT
8
9 Spore is a specification for describing ReST API that can be parsed and used
10 automatically by client implementations to communicate with the descibed API.
11
12 This document describes how to write the description for a ReST API in
13 order to be used with a SPORE Client Implementation.
14
15 =head1 TERMINOLOGY
16
17 =over 4
18
19 =item API
20
21 An I<API> is a ReST application that can exchange data with client
22 applications over http/https. It presents one or more method endpoints which
23 accept http requests with varying headers, parameters and body content to
24 perform specific operations.
25
26 =item Client implementation
27
28 A I<Client implementation> is a library targeting a specific system or
29 language. It can use I<Descriptions files> to create programmatic interfaces
30 usable in applications.
31
32 =item Description file
33
34 A I<Description file> is a file in JSON format describing an I<API> (see
35 specification). It can directly be used by a I<Client implementation> to
36 create a programmatic interface in the target system.
37
38 =back
39
40 =head1 API DESCRIPTION
41
42 An API should provide a description file. The description should be in JSON
43 format.
44
45 =head2 GENERIC DESCRIPTION
46
47 This part describes the API itself:
48
49 =over 4
50
a917f3e3 » ngrunwald
2010-10-13 - transformed numbers in booleans
51 =item B<name> (required)
9d0d0bc5 » franckcuny
2010-10-12 initial import
52
53 A simple name to describe the specification
54
55 name: CouchDB
56
57 =item B<author> (optional)
58
59 A list of authors for this specification
60
61 author:
62 - franck cuny <franck@lumberjaph.net>
63
64 =item B<api_base_url> (optional)
65
66 If the API has a fixed URL
67
68 api_base_url: http://api.twitter.com/1/
69
70 =item B<api_format> (optional)
71
72 A list of supported format
73
74 api_format:
75 - json
76 - xml
77
a917f3e3 » ngrunwald
2010-10-13 - transformed numbers in booleans
78 =item B<version> (required)
9d0d0bc5 » franckcuny
2010-10-12 initial import
79
80 The version number of the current description
81
82 version: 0.1
83
a917f3e3 » ngrunwald
2010-10-13 - transformed numbers in booleans
84 =item B<api_authentication> (optional)
9d0d0bc5 » franckcuny
2010-10-12 initial import
85
86 A boolean to specify if this API requires authentication for all the methods
87
a917f3e3 » ngrunwald
2010-10-13 - transformed numbers in booleans
88 api_authentication: true
89
90 =item B<api_auth_type> (optional)
91
92 A list of supported authentication methods
93
94 api_auth_type:
95 - simple
96 - oauth
9d0d0bc5 » franckcuny
2010-10-12 initial import
97
98 =item B<methods> (required)
99
100 A list of methods
101
102 =back
103
104 The desciption B<MUST> contain a list of at least one method
105
106 =head2 METHOD DESCRIPTION
107
108 A method must have a name:
109
110 public_timeline
111
112 =over 4
113
114 =item B<method> (required)
115
116 An HTTP method
117
118 method: GET
119
120 =item B<path> (required)
121
122 Path for the given method. The path can contain B<placeholders>. A placeholder
123 B<MUST> begin with a <:>:
124
125 path: /statuses/public_timeline.:format
126
127 =item B<params> (optional)
128
129 A list of parameters. This list will be used to replace value in placeholders,
130 and if not used in the path, will be added to the query
131
132 params:
133 - trim_user
134 - include_entities
135
136 =item B<required> (optional)
137
138 A list of required parameters. Parameters that are required B<MUST NOT> be
139 repeated in the B<params> field
140
141 required:
142 - format
143
144 =item B<expected> (optional)
145
146 A list of accepted HTTP status for this method
147
148 expected:
149 - 200
150
151 =item B<description> (optional)
152
153 A simple description for the method. This should not be considered as
154 documentation.
155
156 description: Returns the 20 most recent statuses, including retweets if they exist, from non-protected users
157
158 =item B<authentication> (optional)
159
160 A boolean to specify if this method requires authentication
161
a917f3e3 » ngrunwald
2010-10-13 - transformed numbers in booleans
162 authentication: false
163
164 =item B<auth_type> (optional)
165
166 A list of supported authentication methods
167
168 auth_type:
169 - digest
9d0d0bc5 » franckcuny
2010-10-12 initial import
170
171 =item B<base_url> (optional)
172
173 Specify an url if this method requires a different api_base_url
174
175 api_base_url: http://api.twitter.com/1/
176
177 =item B<format> (optional)
178
179 A list of supported format
180
181 api_format:
182 - json
183 - xml
184
185 =item B<documentation> (optional)
186
187 A complete documentation for the given method
188
189 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.
190
191 =back
192
193 =head3 SAMPLE
194
195 A description for the twitter API (only the API description part and the first method):
196
197 {
198 "api_base_url" : "http://api.twitter.com/1",
199 "version" : "0.1",
200 "methods" : {
201 "public_timeline" : {
202 "params" : [
203 "trim_user",
204 "include_entities"
205 ],
206 "required" : [
207 "format"
208 ],
209 "path" : "/statuses/public_timeline.:format",
210 "method" : "GET"
211 },
212 }
213 }
214
215 =head3 CALLS
216
217 =head1 CHANGELOGS
218
219 0.1: 2010.10.xx
220
221 =over 4
222
223 =item *
224
225 Initial version.
226
227 =back
228
229 =head1 ACKNOWLEDGEMENTS
230
231 Some parts of this specification are adopted from the following specifications.
232
233 =over 4
234
235 =item *
236
237 PSGI Specification L<PSGI|http://search.cpan.org/perldoc?PSGI>
238
239 =item *
240
241 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
242
243 =item *
244
245 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
246
247 =item *
248
249 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
250
251 =back
252
253 I'd like to thank authors of these great documents.
254
255 =head1 AUTHOR
256
257 =over 4
258
259 =item franck cuny
260
261 =item nils grunwald
262
263 =back
264
265 =head1 CONTRIBUTORS
266
267 =over 4
268
269 =item damien "bl0b" leroux
270
271 =back
272
273 =head1 COPYRIGHT AND LICENSE
274
275 Copyright XXX, 2010.
276
277 This document is licensed under the Creative Commons license by-sa.
278
279 =cut
Something went wrong with that request. Please try again.