diff options
Diffstat (limited to '')
| -rw-r--r-- | spore_implementation.pod | 24 |
1 files changed, 12 insertions, 12 deletions
diff --git a/spore_implementation.pod b/spore_implementation.pod index ef06e68..8218651 100644 --- a/spore_implementation.pod +++ b/spore_implementation.pod @@ -2,12 +2,12 @@ =head1 NAME -Spore (Specifications to a POrtable Rest Environment) Client Implementation +Spore (B<S>pecifications to a B<Po>rtable B<R>EST B<E>nvironment) Description Implementation =head1 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. +Spore is a specification for describing REST API that can be parsed and used +automatically by client implementations to communicate with the described API. This document describes what features are required in a Spore client implementation. @@ -18,7 +18,7 @@ implementation. =item API -An I<API> is a ReST application that can exchange data with client +An I<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. @@ -65,13 +65,13 @@ the I<Middlewares> to create the structure returned to the user. A I<Client implementation> B<MUST> provide a function or method (e.g. new_from_spec) to generate the specific API methods in the target system by reading the JSON string from a I<Description file> (and -optionaly directly from the file itself). +optionally directly from the file itself). A I<Client implementation> B<MUST> also provide a method to enable or -disable spore middlewares at runtime. The order in which the +disable spore middlewares at run-time. The order in which the middlewares are enabled 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. It +will go through each optional middleware post-processing callback. It B<MUST> also have a method to selectively enable a middleware or not for each method according to the method properties in the specification. @@ -83,7 +83,7 @@ specification. =head2 Middleware Each middleware B<MUST> accept arbitrary initialization parameters. It -B<MUST> provide a way to only conditionaly use a middleware (e.g. B<enable_if>). It +B<MUST> provide a way to only conditionally use a middleware (e.g. B<enable_if>). It B<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: @@ -104,8 +104,8 @@ made. 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 shortcircuit the remaining of the chain, for -testing or caching purpose for exemple. +if a middleware needs to short-circuit the remaining of the chain, for +testing or caching purpose for example. =back @@ -145,7 +145,7 @@ C<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. +which will be interpolated later with the parameters. If this key is not empty, it B<MUST> start with a forward slash (C</>). @@ -154,7 +154,7 @@ If this key is not empty, it B<MUST> start with a forward slash (C</>). C<REQUEST_URI>: The undecoded, raw request URL line. It is the raw URI path and query part that appears in the HTTP C<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. +placeholders which will be interpolated later with the parameters. =item * |