Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 264 lines (150 sloc) 5.223 kB
9d0d0bc @franckcuny initial import
franckcuny authored
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
a917f3e @ngrunwald - transformed numbers in booleans
ngrunwald authored
51 =item B<name> (required)
9d0d0bc @franckcuny initial import
franckcuny authored
52
53 A simple name to describe the specification
54
55 name: CouchDB
56
b92a4af @franckcuny update specification for the description
franckcuny authored
57 =item B<authority> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
58
b92a4af @franckcuny update specification for the description
franckcuny authored
59 The authority of the description
9d0d0bc @franckcuny initial import
franckcuny authored
60
b92a4af @franckcuny update specification for the description
franckcuny authored
61 authorithy: GITHUB:franckcuny
9d0d0bc @franckcuny initial import
franckcuny authored
62
b92a4af @franckcuny update specification for the description
franckcuny authored
63 =item B<base_url> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
64
65 If the API has a fixed URL
66
b92a4af @franckcuny update specification for the description
franckcuny authored
67 base_url: http://api.twitter.com/1/
9d0d0bc @franckcuny initial import
franckcuny authored
68
b92a4af @franckcuny update specification for the description
franckcuny authored
69 =item B<formats> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
70
71 A list of supported format
72
b92a4af @franckcuny update specification for the description
franckcuny authored
73 formats:
9d0d0bc @franckcuny initial import
franckcuny authored
74 - json
75 - xml
76
a917f3e @ngrunwald - transformed numbers in booleans
ngrunwald authored
77 =item B<version> (required)
9d0d0bc @franckcuny initial import
franckcuny authored
78
79 The version number of the current description
80
81 version: 0.1
82
a917f3e @ngrunwald - transformed numbers in booleans
ngrunwald authored
83 =item B<api_authentication> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
84
85 A boolean to specify if this API requires authentication for all the methods
86
b92a4af @franckcuny update specification for the description
franckcuny authored
87 authentication: true
9d0d0bc @franckcuny initial import
franckcuny authored
88
89 =item B<methods> (required)
90
91 A list of methods
92
93 =back
94
95 The desciption B<MUST> contain a list of at least one method
96
97 =head2 METHOD DESCRIPTION
98
99 A method must have a name:
100
101 public_timeline
102
103 =over 4
104
105 =item B<method> (required)
106
107 An HTTP method
108
109 method: GET
110
111 =item B<path> (required)
112
113 Path for the given method. The path can contain B<placeholders>. A placeholder
114 B<MUST> begin with a <:>:
115
116 path: /statuses/public_timeline.:format
117
b92a4af @franckcuny update specification for the description
franckcuny authored
118 =item B<optional_params> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
119
b92a4af @franckcuny update specification for the description
franckcuny authored
120 A list of optional parameters. This list will be used to replace value in placeholders, and if not used in the path, will be added to the query
9d0d0bc @franckcuny initial import
franckcuny authored
121
b92a4af @franckcuny update specification for the description
franckcuny authored
122 optional_params:
9d0d0bc @franckcuny initial import
franckcuny authored
123 - trim_user
124 - include_entities
125
b92a4af @franckcuny update specification for the description
franckcuny authored
126 =item B<required_params> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
127
b92a4af @franckcuny update specification for the description
franckcuny authored
128 A list of required parameters. Parameters that are required B<MUST NOT> be repeated in the B<optional_params> field
9d0d0bc @franckcuny initial import
franckcuny authored
129
b92a4af @franckcuny update specification for the description
franckcuny authored
130 required_params:
9d0d0bc @franckcuny initial import
franckcuny authored
131 - format
132
b92a4af @franckcuny update specification for the description
franckcuny authored
133 =item B<expected_status> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
134
135 A list of accepted HTTP status for this method
136
b92a4af @franckcuny update specification for the description
franckcuny authored
137 expected_status:
9d0d0bc @franckcuny initial import
franckcuny authored
138 - 200
139
140 =item B<description> (optional)
141
142 A simple description for the method. This should not be considered as
143 documentation.
144
145 description: Returns the 20 most recent statuses, including retweets if they exist, from non-protected users
146
147 =item B<authentication> (optional)
148
149 A boolean to specify if this method requires authentication
150
a917f3e @ngrunwald - transformed numbers in booleans
ngrunwald authored
151 authentication: false
152
9d0d0bc @franckcuny initial import
franckcuny authored
153 =item B<base_url> (optional)
154
155 Specify an url if this method requires a different api_base_url
156
b92a4af @franckcuny update specification for the description
franckcuny authored
157 base_url: http://api.twitter.com/1/
9d0d0bc @franckcuny initial import
franckcuny authored
158
b92a4af @franckcuny update specification for the description
franckcuny authored
159 =item B<formats> (optional)
9d0d0bc @franckcuny initial import
franckcuny authored
160
161 A list of supported format
162
b92a4af @franckcuny update specification for the description
franckcuny authored
163 formats:
9d0d0bc @franckcuny initial import
franckcuny authored
164 - json
165 - xml
166
167 =item B<documentation> (optional)
168
169 A complete documentation for the given method
170
171 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.
172
173 =back
174
175 =head3 SAMPLE
176
177 A description for the twitter API (only the API description part and the first method):
178
179 {
b92a4af @franckcuny update specification for the description
franckcuny authored
180 "base_url" : "http://api.twitter.com/1",
9d0d0bc @franckcuny initial import
franckcuny authored
181 "version" : "0.1",
182 "methods" : {
183 "public_timeline" : {
b92a4af @franckcuny update specification for the description
franckcuny authored
184 "optional_params" : [
9d0d0bc @franckcuny initial import
franckcuny authored
185 "trim_user",
186 "include_entities"
187 ],
b92a4af @franckcuny update specification for the description
franckcuny authored
188 "required_params" : [
9d0d0bc @franckcuny initial import
franckcuny authored
189 "format"
190 ],
191 "path" : "/statuses/public_timeline.:format",
192 "method" : "GET"
b92a4af @franckcuny update specification for the description
franckcuny authored
193 }
9d0d0bc @franckcuny initial import
franckcuny authored
194 }
195 }
196
197 =head3 CALLS
198
199 =head1 CHANGELOGS
200
201 0.1: 2010.10.xx
202
203 =over 4
204
205 =item *
206
207 Initial version.
208
209 =back
210
211 =head1 ACKNOWLEDGEMENTS
212
213 Some parts of this specification are adopted from the following specifications.
214
215 =over 4
216
217 =item *
218
219 PSGI Specification L<PSGI|http://search.cpan.org/perldoc?PSGI>
220
221 =item *
222
223 PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>
224
225 =item *
226
227 Rack L<http://rack.rubyforge.org/doc/SPEC.html>
228
229 =item *
230
231 JSGI Specification L<http://jackjs.org/jsgi-spec.html>
232
233 =back
234
235 I'd like to thank authors of these great documents.
236
237 =head1 AUTHOR
238
239 =over 4
240
241 =item franck cuny
242
243 =item nils grunwald
244
245 =back
246
247 =head1 CONTRIBUTORS
248
249 =over 4
250
251 =item damien "bl0b" leroux
252
b92a4af @franckcuny update specification for the description
franckcuny authored
253 =item François Perrad
254
9d0d0bc @franckcuny initial import
franckcuny authored
255 =back
256
257 =head1 COPYRIGHT AND LICENSE
258
259 Copyright XXX, 2010.
260
261 This document is licensed under the Creative Commons license by-sa.
262
263 =cut
Something went wrong with that request. Please try again.