Spore (Specifications to a POrtable Rest Environment) Description Implementation
Spore is a specification for describing ReST API that can be parsed and used automatically by client implementations to communicate with the descibed API.
This document describes how to write the description for a ReST API in order to be used with a SPORE Client Implementation.
An API is a ReST application that can exchange data with client applications over http/https. It presents one or more method endpoints which accept http requests with varying headers, parameters and body content to perform specific operations.
A Client implementation is a library targeting a specific system or language. It can use Descriptions files to create programmatic interfaces usable in applications.
A Description file is a file in JSON format describing an API (see specification). It can directly be used by a Client implementation to create a programmatic interface in the target system.
An API should provide a description file. The description should be in JSON format.
This part describes the API itself:
A simple name to describe the specification
name: CouchDB
A list of authors for this specification
author:
- franck cuny <franck@lumberjaph.net>
If the API has a fixed URL
api_base_url: http://api.twitter.com/1/
A list of supported format
api_format:
- json
- xml
The version number of the current description
version: 0.1
A boolean to specify if this API requires authentication for all the methods
authentication: 1
A list of methods
The desciption MUST contain a list of at least one method
A method must have a name:
public_timeline
An HTTP method
method: GET
Path for the given method. The path can contain placeholders. A placeholder MUST begin with a <:>:
path: /statuses/public_timeline.:format
A list of parameters. This list will be used to replace value in placeholders, and if not used in the path, will be added to the query
params:
- trim_user
- include_entities
A list of required parameters. Parameters that are required MUST NOT be repeated in the params field
required:
- format
A list of accepted HTTP status for this method
expected:
- 200
A simple description for the method. This should not be considered as documentation.
description: Returns the 20 most recent statuses, including retweets if they exist, from non-protected users
A boolean to specify if this method requires authentication
authentication: 0
Specify an url if this method requires a different api_base_url
api_base_url: http://api.twitter.com/1/
A list of supported format
api_format:
- json
- xml
A complete documentation for the given method
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.
A description for the twitter API (only the API description part and the first method):
{
"api_base_url" : "http://api.twitter.com/1",
"version" : "0.1",
"methods" : {
"public_timeline" : {
"params" : [
"trim_user",
"include_entities"
],
"required" : [
"format"
],
"path" : "/statuses/public_timeline.:format",
"method" : "GET"
},
}
}
0.1: 2010.10.xx
Some parts of this specification are adopted from the following specifications.
I'd like to thank authors of these great documents.
Copyright XXX, 2010.
This document is licensed under the Creative Commons license by-sa.
