Steven Haryanto > Riap > Riap::HTTP

Download:
Riap-1.1.24.tar.gz

Annotate this POD

Website

View/Report Bugs
Source  

NAME ^

Riap::HTTP - Riap over HTTP

VERSION ^

This document describes version 1.1.24 of Riap::HTTP (from Perl distribution Riap), released on 2014-08-18.

SYNOPSIS ^

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

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::Simple.

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

Additional Riap request keys

Additional actions

Action: srvinfo

Just like info action, but get information about the server instead. Server MUST at least return the following keys in the result hash.

 {
  // server's absolute URL
  "srvurl": "http://localhost:5000/",

  // supported formats
  "fmt": ["Console","HTML","JSON","PHPSerialization","YAML","json"],
 }

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 a common access mechanism.

The server MUST also accept args from HTTP request body. The server MUST accept at least body of type application/json, but it can accept other types. The server MUST not interpret application/x-www-form-urlencoded for this purpose (and interpret it as a normal web form). Server MUST return response 400 if document type is not recognized.

The server can also accept Riap request keys or function arguments using other means. For example, Plack::Middleware::PeriAHS::ParseRequest, from Perl server implementation, allows parsing Riap request keys like uri from URI path, and args keys (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": '/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 Riap request:

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

SPECIFICATION VERSION ^

 1.1

HTTP RESPONSE ^

Response status MUST be 200 for success.

There are some HTTP response headers related to Riap::HTTP: X-Riap-V is REQUIRED and gives information on the Riap::HTTP protocol version supported by the server. X-Riap-Logging is optional and advertises loglevel server support (see "LOGGING").

The response body is an enveloped result (as described in Rinci::function) encoded in JSON or other format.

LOGGING ^

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

Server can opt NOT to support this feature. Server supporting this feature MUST advertise the fact by sending HTTP response header X-Riap-Logging with a Perl true value.

Additional Riap request key loglevel is recognized for this, 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 is specified, server supporting this feature must return chunked HTTP response and each log message should be sent as a separate chunk. Each log message must be prepended with "l" followed by number of bytes of content (e.g. "20") followed by a single space character followed by the content (in this example, exactly 20 bytes of it). Result is similarly prepended but with "r" instead of "l".

EXAMPLES ^

Below are some examples of what is sent and received over the wire. For these examples, the server has the following URL scheme http://example.org/api/<URI>. Server also assume the default values for these Riap request keys so they do not have to be specified by client: v (1.1), action (call).

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

 --- Request ---
 GET /api/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: PeriAHS/0.01
 X-Riap-V: 1.1.21
 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/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: PeriAHS/0.01
 X-Riap-V: 1.1.21
 Content-Type: application/json

 [200,"OK",6]

Another example demonstrating loglevel. Note that if server does not send X-Riap-Logging response header, it means the server does not support logging and send 'unlogged' response.

 --- Request ---
 GET /Perinci/Examples/call_randlog?-riap-loglevel=6&n=3 HTTP/1.1
 User-Agent: curl/7.30.0
 Host: localhost:5000
 Accept: */*

 --- Response ---
 HTTP/1.1 200 OK
 Server: Gepok/0.24
 Content-Type: text/plain
 Date: Sat, 21 Dec 2013 06:18:13 GMT
 Connection: Keep-Alive
 Transfer-Encoding: chunked
 X-Riap-V: 1.1.21
 X-Riap-Logging: 1

 l96 [critical][Sat Dec 21 13:18:13 2013] (1/3) This is random log message #1, level=1 (fatal): 2185
 l93 [trace][Sat Dec 21 13:18:13 2013] (2/3) This is random log message #2, level=6 (trace): 5845
 l93 [trace][Sat Dec 21 13:18:13 2013] (3/3) This is random log message #3, level=6 (trace): 3479

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
 PATCH /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::Simple

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/Riap.

SOURCE ^

Source repository is at https://github.com/sharyanto/perl-Riap.

BUGS ^

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Riap

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR ^

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

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

syntax highlighting: