/ 
Net-HTTP-Spore-0.03
River stage two • 9 direct dependents • 10 total dependents
/ Spore

NAME

Spore (Specifications to a POrtable Rest Environment) Description Implementation

ABSTRACT

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.

TERMINOLOGY

API

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.

Client implementation

A Client implementation is a library targeting a specific system or language. It can use Descriptions files to create programmatic interfaces usable in applications.

Description file

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.

API DESCRIPTION

An API should provide a description file. The description should be in JSON format.

GENERIC DESCRIPTION

This part describes the API itself:

name (optional)

A simple name to describe the specification

name: CouchDB
author (optional)

A list of authors for this specification

author:
  - franck cuny <franck@lumberjaph.net>
api_base_url (optional)

If the API has a fixed URL

api_base_url: http://api.twitter.com/1/
api_format (optional)

A list of supported format

api_format:
  - json
  - xml
version (optinal)

The version number of the current description

version: 0.1
authentication (optional)

A boolean to specify if this API requires authentication for all the methods

authentication: 1
methods (required)

A list of methods

The desciption MUST contain a list of at least one method

METHOD DESCRIPTION

A method must have a name:

public_timeline
method (required)

An HTTP method

method: GET
path (required)

Path for the given method. The path can contain placeholders. A placeholder MUST begin with a <:>:

path: /statuses/public_timeline.:format
params (optional)

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
required (optional)

A list of required parameters. Parameters that are required MUST NOT be repeated in the params field

required:
  - format
expected (optional)

A list of accepted HTTP status for this method

expected:
  - 200
description (optional)

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
authentication (optional)

A boolean to specify if this method requires authentication

authentication: 0
base_url (optional)

Specify an url if this method requires a different api_base_url

api_base_url: http://api.twitter.com/1/
format (optional)

A list of supported format

api_format:
  - json
  - xml
documentation (optional)

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.

SAMPLE

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"
        },
    }
}

CALLS

CHANGELOGS

0.1: 2010.10.xx

  • Initial version.

ACKNOWLEDGEMENTS

Some parts of this specification are adopted from the following specifications.

I'd like to thank authors of these great documents.

AUTHOR

franck cuny
nils grunwald

CONTRIBUTORS

damien "bl0b" leroux

COPYRIGHT AND LICENSE

Copyright XXX, 2010.

This document is licensed under the Creative Commons license by-sa.