The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-HTTP-Spore-0.03
River stage two • 9 direct dependents • 10 total dependents
9 ++
/ Spore

NAME

Spore (Specifications to a POrtable Rest Environment) Client 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 what features are required in 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.

Middleware

A Middleware is Spore component that is added to the workflow of the Client implementation to modify the Requests and responses sent and received. It can also shortcircuit the rest of the workflow if needed. It can be thought of a plugin to extend Spore.

Request

A Request is a data structure that contains standardized data and metadata inspired by the CGI specification. It is used by the Client implementation to create the http request that will be sent to the API.

Response

A Response is a data structure that contains standardized data and metadata inspired by the CGI specification. It is created from the http response sent by the API and is used after being processed by the Middlewares to create the structure returned to the user.

SPECIFICATION

Client Implementation

A Client implementation MUST provide a function or method (eg. new_from_spec) to generate the specific API methods in the target system by reading the JSON string from a Description file (and optionaly directly from the file itself).

A Client implementation MUST also provide a method to enable or disable spore middlewares at runtime. The order in which the middlewares are enambled is the order in which the request will go through each middleware, and the inverse order in which the response will go through each optional middleware postprocessing callback.

  If middlewares I<A>, I<B> and I<C> were enabled in this order, then
  the processing order will be:
    I<A>, I<B>, I<C> ... make request ... I<C>, I<B>, I<A>

Middleware

Each middleware MUST accept arbitrary initialization parameters. It MUST also provide a function to which the request environment or an object containing it will be passed. The function can have 3 types of return values :

Nothing

Control is passed to the next middleware in the chain.

A callback

Control is passed to the next middleware in the chain. The callback is stored and will be passed the response later on after the request is made.

A response

The response is directly passed to the first stored callback in the chain. No further middlewares are used and no request is sent. Useful if a middleware needs to shortcicuit the remaining of the chain, for testing or caching purpose for exemple.

The Request environment

The request environment MUST be a data structure that includes CGI-like headers, as detailed below. Each middleware is free to modify the environment. The environment MUST include these keys (adopted from PEP 333, Rack, PSGI and JSGI) except when they would normally be empty. The environment is used by the Client implementation to build the final http request that will be sent to the API.

  • REQUEST_METHOD: The HTTP request method, such as "GET" or "POST". This MUST NOT be an empty string, and so is always required.

  • SCRIPT_NAME: The initial portion of the base URL's path, minus the schema and domain name. This tells the client what is the API virtual "location". This may be an empty string if the method corresponds to the server's root URI.

    If this key is not empty, it MUST start with a forward slash (/).

  • PATH_INFO: The remainder of the request URL's path, designating the virtual "location" of the request's target within the API. This may be an empty string if the request URL targets the application root and does not have a trailing slash. It still contains the placeholders which will be interpolated later with the params.

    If this key is not empty, it MUST start with a forward slash (/).

  • REQUEST_URI: The undecoded, raw request URL line. It is the raw URI path and query part that appears in the HTTP GET /... HTTP/1.x line and doesn't contain URI scheme and host names. It still contains the placeholders which will be interpolated later with the params.

  • SERVER_NAME, SERVER_PORT: When combined with SCRIPT_NAME and PATH_INFO, these keys can be used to complete the URL. Note, however, that HTTP_HOST, if present, should be used in preference to SERVER_NAME for reconstructing the request URL. SERVER_NAME and SERVER_PORT MUST NOT be empty strings, and are always required.

  • QUERY_STRING: The portion of the request URL that follows the ?, if any. May be empty, but is always required. It will always be empty before the request is actually made and sent.

  • spore.payload: The actual content body of the call. Modified in place by the middlewares.

  • spore.params: A list of key/value pairs. These will be interpolated in the url with the placeholders when the request is made. The rest of them will be used in the QUERY_STRING part of the uri. B>MAY> be empty but MUST always be present.

  • spore.scheme: !!! Check if url_scheme !! The scheme of the url.

  • spore.scheme: !!! Check if url_scheme !! The scheme of the url.

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.