NAME Sub::Spec::HTTP - Specification for sub and spec operations over HTTP VERSION version 1.0.0 DESCRIPTION This is a specification for calling remote subroutines, or doing other sub-/spec-related operations over HTTP. The specification should be implemented by servers and clients written in Perl or other languages. SPECIFICATION VERSION 1.0 TERMINOLOGIES * SS request An SS request (SS being a short for Sub::Spec) is a hash containing some keys like: "command", "sub", "module", "args", "resp_format", "log_level", "mark_log". See "SS REQUEST" * SS server An SS server is an HTTP server. It should parse SS request from HTTP request and then execute the SS request and return the result as HTTP response. Sub::Spec::HTTP::Server is the de facto Perl server implementation. * SS client An SS client is a library or program which sends requests to an SS server over HTTP. It should provide some transparency to its user, creating some level of illusion that the user is accessing a local sub/spec. Sub::Spec::HTTP::Client is the de facto Perl client implementation. SS REQUEST An SS request is a hashref containing some predefined keys, listed below. SS server SHOULD return an HTTP 400 error code if client sends an unknown key. Not all keys are required for each request. * command => STR Always required. Default command is 'call'. The list of all currently known commands are written below. A server should implement some or all of the listed commands. It SHOULD return HTTP 502 status if a command is unknown. It can implement new commands if deemed necessary. 'about' command, to request information about the server. For this command, no other request key is necessart. The server MUST return a hashref like this: { version => [1, 0], # Sub::Spec::HTTP specification version input_formats => [qw/json phps yaml/], # supported input formats output_formats => [qw/json pretty nopretty yaml phps html/], # supported output formats # other extra keys are allowed } 'call' command, to call a subroutine and return its result. For this command, at least 'module' and 'sub' are required. 'args' is also required, but will default to {} (empty hash) if not specified. 'list_commands' command, to list known commands. No other request key is necessary. 'list_mods' command, to list known modules. No other request key is necessary. 'list_subs' command, to list known subroutines in a module. Request key 'module' is required. 'usage' command, to show subroutine's usage (like list of arguments and description for each). Request keys 'sub' and 'module' are required. 'spec' command, to request spec for a subroutine. Request keys 'sub' and 'module' are required. * module => STR To specify module name. All groups of nonalphanumeric characters SHOULD be converted to server's language, for example: Foo.Bar_Baz should be converted to Foo::Bar_Baz by the Perl server. If invalid module name is specified, server MUST return HTTP 400. * sub => STR To specify subroutine name. If invalid subroutine name is specified, server MUST return 400. * args => HASH (default {}) To specify arguments. Must be a hashref, or the server MUST return 400. * output_format => STR To specify response format. Known formats are 'yaml', 'json', 'php', 'pretty', 'simple', 'html'. A server can support more formats, but at least it MUST support 'json'. Server can pick default format as it deems necessary/convenient. * log_level => INT|STR (default 0) Am integer number between 0 (lowest, none) and 6 (highest, trace) or string (either "none" [0], "fatal" [1], "error" [2], "warn" [3], "info" [4], "debug" [5], "trace" [6]). Relevant only for 'call' command. When specified, a server should return log messages (e.g. produced by Log::Any) to the client in the HTTP response. * mark_log => BOOL (default 0) If set to true, prepend each log message with "L" (and response with "R") in each response chunk. Only useful/relevant when turning on log_level > 0, so clients can parse/separate log message from response. SS SERVER An SS server listens to HTTP requests, parsing them into SS requests, and execute the SS requests for clients. Parsing SS request from HTTP request Server at least MUST parse SS request keys from HTTP "X-SS-Req-*" request headers, e.g. "X-SS-Req-Command" header for setting the "command" request key. In addition, the server MUST parse "X-SS-Req-*-j" for JSON-encoded value, e.g. X-SS-Req-Args-j: {arg1:"val1",arg2:[1,2,3]} should set "args" request key to "{arg1 =" "val1", arg2 => [1, 2, 3]}>. The server MUST also accept request body for "args". The server MUST accept at least body of type "application/json". It can accept additional types if it wants, e.g. "text/yaml" or "application/vnd.php.serialized". The server can also accept SS request keys or sub arguments using other means, for example, Sub::Spec::HTTP::Server allows setting "module" and "sub" from URI path, and arguments (as well as other SS request keys, using "-ss-req-*" syntax) from request variables. For example: http://HOST/api/MOD::SUBMOD/FUNC?arg1=val1&arg2:j=[1,2]&-ss-req-command=spec will result in the following SS request: { command => 'spec', module => 'MOD::SUBMOD', sub => 'FUNC', args => {arg1=>'val1', arg2=>[1, 2]}, } SS CLIENT SEE ALSO Sub::Spec AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2011 by Steven Haryanto. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.