NAME

Riap::HTTP - Riap over HTTP

VERSION

version 1.1.7

DESCRIPTION

Riap::HTTP is designed to be implemented by API service providers. It allows features like custom URL layout, multiple serialization format, and logging; while depends on HTTP for other features like authentication, encryption (HTTPS), etc. For a more lightweight alternative, look at Riap::TCP.

Server listens to HTTP requests, parses them into Riap requests, executes the Riap requests, and sends the results to clients.

Additional Riap request keys

• fmt => STR

  Specify serialization format to use. Defaults to json, which the server MUST accept. Server can accept additional result formats if it wants to, like yaml, xml, or phps (PHP serialization format).

  Server should give response in json if requested result format is not supported.

Additional info keys

For the info action on the root package entity, these additional keys MUST be returned by the server:

{
 // server's absolute URL
 "srvurl": "riap+tcp://localhost:5000/",

 // supported serialization formats
 "fmt": ["json","yaml","phps"],
}

Parsing Riap request from HTTP request

Server can provide defaults for some/all Riap request keys, so client does not need to explicitly set a Riap request key. But server MUST provide a way for client to set any Riap request key.

First, server MUST parse Riap request keys from HTTP X-Riap-* request headers, e.g. X-Riap-Action header for setting the action request key. In addition, the server MUST parse the X-Riap-*-j- headers for JSON-encoded value (notice the ending -), e.g.

X-Riap-Args-j-: {"arg1":"val1","arg2":[1,2,3]}

This allows the server to have its own URL scheme, while allowing a way for common access mechanism.

The server MUST also accept args from HTTP request body. 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 Rinci request keys or function arguments using other means, for example, Plack::Access::HTTP::Server, a Perl server implementation, allows parsing uri from URI path, and function arguments (as well as other Riap request keys, using -riap-* syntax) from request variables. For example:

http://HOST/api/PKG/SUBPKG/FUN?a1=1&a2:j=[1,%202]

might result in the following Riap request:

{
 "uri": 'pm:/My/App/PKG/SUBPKG/FUN',
 "action": 'call',
 "args": {"a1":1, "a2":[1,2]},
}

Another example:

http://HOST/api/PKG/FUN?-riap-action=complete_arg_val&-riap-arg=a1&-riap-word=x

will result in the following Rinci request:

{
 "uri": 'pm:/PKG/FUN',
 "action": 'complete_arg_val',
 "arg": 'a1',
 "word": 'x',
}

SPECIFICATION VERSION

1.1

ABSTRACT

This document specifies using HTTP/HTTPS as the transport layer for Riap, or Riap::HTTP for short.

LOGGING

Riap over HTTP also allows a mechanism to pass logging messages during function calls by using HTTP chunked response.

Two additional Riap request keys are recognized for this:

• loglevel

  An integer number with value either 0 (for none, the default), 1 (for sending fatal messages), 2 (error), 3 (warn), 4 (info), 5 (debug), and 6 (trace). When a value larger than 0 specified, server must return chunked HTTP response and each log message should be sent as a separate chunk, and the result as the last chunk.

• marklog

  A bool, default to 0. When set to true, server will prepend each log message with "L" (and the result with "R"). Only useful/relevant when turning on loglevel, so clients can parse/separate log message from result.

EXAMPLES

Below are some examples of what is sent and received on the wire. For these examples, the server has the following URL scheme http://example.org/api/v1/<URI>. It detects desired output format from the Accept HTTP request header.

Call a function, passing function arguments via query parameter, unsuccessfully because of missing argument:

--- Request ---
GET /api/v1/Math/multiply2?a=2 HTTP/1.0
Accept: application/json

--- Response ---
HTTP/1.0 200 OK
Date: Sat, 14 Jan 2012 17:11:40 GMT
Server: Perinci::Access::HTTP::Server/0.01
Content-Type: application/json

[400,"Missing required argument: b"]

Call the same function, successfully this time. As a variation we pass function arguments through the X-Riap-Args HTTP header:

--- Request ---
GET /api/v1/Math/multiply2 HTTP/1.0
X-Riap-Args-j-: {"a":2,"b":3}
Accept: application/json

--- Response ---
HTTP/1.0 200 OK
Date: Sat, 14 Jan 2012 17:11:50 GMT
Server: Perinci::Access::HTTP::Server/0.01
Content-Type: application/json

[200,"OK",6]

FAQ

Why not directly return status from enveloped result as HTTP response status?

Since enveloped result is modeled somewhat closely after HTTP message, especially the status code, it might make sense to use the status code directly as HTTP status. But this means losing the ability to differentiate between the two. We want the client to be able to differentiate whether the 500 (Internal server error) or 404 (Not found) code it is getting is from the HTTP server/proxies/client or from the enveloped result.

Riap/Riap::HTTP vs REST? Which one to choose for my web service?

Riap maps code entities (packages and functions), while REST maps resources (like business entities) to URI's. For example:

# Riap
/User/             # package
/User/list_users   # function
/User/create_user  # function

# REST (verb + URI)
GET /user          # list users
GET /user/123      # get specific user
POST /user         # create a new user
PUT /user/123      # modify user
DELETE /user/123

Riap is more RPC style, and it is more straightforward if you want to export a set of code modules and functions as API. But it also defines standard and extensible "verbs" (actions). It also helps service discoverability and self-description due to the list action and the rich Rinci metadata. Riap::HTTP can also use custom routing so if you want you can make it use REST style, while still fulfilling request with Riap in the backend. For example, see Serabi in Perl.

SEE ALSO

Riap::TCP

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 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.

cpanm Riap

perl -MCPAN -e shell
install Riap