/ 
OpenResty-0.5.12
River stage zero No dependents
/ OpenResty::Spec::REST

NAME

OpenResty::Spec::REST - OpenResty REST Service Specification [draft]

AUTHOR

Agent Zhang (agentzh) <agentzh@yahoo.cn>

VERSION

CREATED:            Nov 19, 2007
LAST MODIFIED:      Feb 28, 2008
VERSION:            1.00

LICENSE

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

DESCRIPTION

This document defines the REST API for the OpenResty protocol, an web service interface to relational databases.

Login

Anonymous login

Login by password

Per-request-login

Login by captchas

Models

Operations on the model list

Operations on a model

Operations on a model column

Operations on model rows

Views

Operations on the view list

Operations on a view

Operations on a view param

Invoking a view

Actions

Operations on the action list

Operations on an action

Operations on an action param

Invoking an action

Roles

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.

Operations on the role list

Read all the existing roles

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 all the roles

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."}

Operations on a role

Create a role

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".

Read a role's meta info

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 a role's meta info

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

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.

Operations on a role's access rules

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.

Insert new ACL rules

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

Query existing ACL rules

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.

Update existing ACL rules

Delete existing ACL rules