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":"/=/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.
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.
The password field in the JSON body for creating a new role can only appear when the login field is of the value "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>:
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.
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.
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.
