OpenResty::Spec::REST - OpenResty REST Service Specification [draft]
Agent Zhang (agentzh) <agentzh@yahoo.cn>
CREATED: Nov 19, 2007 LAST MODIFIED: Feb 28, 2008 VERSION: 1.00
Copyright (c) 2007, 2008 Yahoo! China, Alibaba Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found at http://www.gnu.org/licenses/fdl.html
This document defines the REST API for the OpenResty protocol, an web service interface to relational databases.
Roles are first-order objects in OpenResty, just as models, views, and actions. Roles have very similar interface to models, in particular. You'll notice the strong parallels between these two.
GET /=/role
The server returns a list of hashes for all the roles available in the account. Each hash corresponds to a role, containing the fields src, name, and description. A sample response is given below:
src
name
description
[ {"src":"/=/role/Admin","name":"Admin","description":"Administrator"}, {"src":"/=/role/Public","name":"Public","description":"Anonymous"}, {"src":"/=/role/Newposter","name":"Newposter","description":"Comment poster"} ]
Note that built-in roles Admin and Public are reserved and will always get shown here.
Admin
Public
DELETE /=/role
Note that built-in roles Admin and Public will always be skipped. A typical server response is
{"success":1,"warning":"Predefined roles skipped."}
POST /=/role/~ { name: <role_name>, description: <role_description>, login: <login_method>, password: <password>, }
<login_method> can be one of the following: anonymous, password, and captcha. See the "Login" section for more information regarding these different login methods.
<login_method>
anonymous
password
captcha
The password field in the JSON body for creating a new role can only appear when the login field is of the value "password".
login
"password"
GET /=/role/<role_name>
A typical response from the server is
{ "columns":[ {"name":"id","label":Rule ID"","type":"serial"} {"name":"method","label":"HTTP method","type":"text"}, {"name":"url","label":"Resource","type":"text"} ], "name":"Poster", "description":"My Poster Role", "login":"password" }
Note that the password field won't get shown even if the login field is "password".
Update some properties (name, login, password, and etc.) for role <role_name>:
<role_name>
PUT /=/role/<role_name> { <key>:<new_value>, ... }
The following example
PUT /=/role/Poster { name: "NewPoster", password: 5906438 }
changes the name of the Poster role to NewPoster and also changes its password to 5906438.
Poster
NewPoster
5906438
Delete a role named <role_name>:
DELETE /=/role/<role_name>
For instance,
DELETE /=/role/Poster
removes the Poster role (as well as its associative ACL rules) completely.
One can manipulate a role's ACL rules with the same interface as model rows. Every role can be considered a special model with three columns, id, method and url.
id
method
url
One can insert one rule at a time:
POST /=/role/<role_name>/~/~ { method: <HTTP_method_allowed>, url: <url_pattern_allowed> }
or insert multiple rules in a single request:
POST /=/role/<role_name>/~/~ [ { method: <HTTP_method_allowed>, url: <url_allowed> }, ... ]
Here is an example:
POST /=/role/Public/~/~ [ {"method":"POST","url":"/=/model/~"}, {"method":"GET","url":"/=/model/A/~/~"}, {"method":"DELETE","url":"/=/model/A/id/~"} ]
This request inserts 3 ACL rules for the Public role. Tild ~ is a match-any wildcard. And at least the following requests are allowed for the Public role:
~
POST /=/model/~ POST /=/model/Moose GET /=/model/A/id/3 GET /=/model/A/~/~ DELETE /=/model/A/id/2 DELETE /=/model/A/id/52
One can obtain all the ACL rules by using
GET /=/role/<role_name>/~/~
or limit the rules by a rule column
GET /=/role/<role_name>/<column>/<value>
which only returns the rules with column column equal to value.
column
value
To install OpenResty, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenResty
CPAN shell
perl -MCPAN -e shell install OpenResty
For more information on module installation, please visit the detailed CPAN module installation guide.