=head1 NAME

OpenResty::CheatSheet - Cheat sheet for OpenResty

=head1 DESCRIPTION

This 'cheat sheet' is a handy reference, meant for beginning OpenResty users.
Not everything is mentioned, but most of the common features in
L<OpenResty::Spec::REST> may already be included.

Note that in the following small examples the plain password passing
on the URL is merely a hack in the currrent implementation
(just for my development convenience).
It is supposed to be encrypted on the client side first (with a
random salt obtained from the OpenResty server) I<and> all go through
SSL in the real thing.

=head1 LOGIN API

    GET /=/login/agentzh.Admin/password   Login as account "agentzh" and
                                          role "Admin" using encrypted
                                          password "password"
    DELETE /=/view/Blah?user=agentzh.Admin&password=password

=head1 MODEL API

=over

=item Model Lists

    GET /=/model                    Read model list
    DELETE /=/model                 Delete all models

=item Models

    GET /=/model/MyModel            Read the info for MyModel
    POST /=/model/MyModel           Create a model MyModel
        { description:"Model description",
          columns:[
            {
              name:"title",label:"Title",
              type:"text",default:"No title",
              required:1
            },
            {
              name:"gender",label:"Gender",
              values:['M','F']
            },
            ...
          ] }

    PUT /=/model/MyModel            Alter the model MyModel
        { name:"NewName",description:"New Description" }

    DELETE /=/model/MyModel         Delete model MyModel

=item Columns

    GET /=/model/MyModel/mycol      Read the info for MyModel's mycol
    POST /=/model/MyModel/mycol     Add a new column named mycol
        { label:"My column",type:"integer",default:0 }

    PUT /=/model/MyModel/mycol      Alter the column mycol
        { name:"new_name", type:"real" }

    DELETE /=/model/MyModel/mycol   Remove column mycol

=item Rows

    GET /=/model/MyModel/id/3       Read the row with id 3
    POST /=/model/MyModel/~/~       Insert new rows
        [ { col1:"", col2:"", ... }, ... ]

    POST /=/model/MyModel/~/~       Insert a single new row
        { col1:"", col2:"", ... }

    PUT /=/model/MyModel/id/2       Update the row with id 2
        { col1:"", col2:"", ... }

    DELETE /=/model/MyModel/id/2    Delete the row with id 2
    DELETE /=/model/MyModel/~/~     Delete all the rows

=item Parameters

    GET /=/model/MyModel/~/~?order_by=col1              order by col1
    GET /=/model/MyModel/~/~?order_by=col1,col2         order by col1, col2
    GET /=/model/MyModel/~/~?order_by=col1:asc,col2:desc
                                                        order by col1 asc, col2 desc
    GET /=/model/MyModel/~/~?offset=10&count=20         offset 10 limit 20

=back

=head1 VIEW API

=over

=item View lists

    GET /=/view                     Get a list of all the views available
    DELETE /=/view                  Delete all the views

=item Views

    POST /=/view/MyView             Create a new view named MyView which
    { description:"My view",        takes the parameters "table" and "min"
      definition:
        "select * from Post, $table where Post.id >= $min"
    }

    GET /=/view/MyView              View the definition of the view MyView
    PUT /=/view/MyView              Update the information of MyView
    { name:"NewName", description:"New desc" }

    DELETE /=/view/NewName           Remove the NewName view

=item Calling views

    GET /=/view/MyView/~/~?table=Comment&min=100

    # assuming the PostsByMonth view has 2 parameters, "year" and "month"
    GET /=/view/PostsByMonth/~/~?year=2008&month=3?
    GET /=/view/PostsByMonth/year/2008?month=3
    GET /=/view/PostsByMonth/month/3?year=2008

=back

=head1 ACTION API

B<Note:> Actions have not yet been implemented.

=over

=item Action lists

    GET /=/action           Get the list of all the existing actions
    DELETE /=/action        Remove all the actions (except built-in ones)

=item Actions

    POST /=/action/PostComment              Create an action for posting
    { description:"Post a comment",         new comments
      definition:"
        POST /=/model/Comment/~/~
        { author:   $author,
          content:  $content,
          post:     $post }
        update Post set comments=comments+1
        where post = $post" }

    PUT /=/action/PostComment               Update an existing action
    { name:"SendComment",
      description:"Send a comment" }

=item Calling actions

    POST /=/action/PostComment/~/~       Invoke the PostComment action
    { author:"agentzh",                  defined above
      content:"Good post!",
      post:125 }

=back

=head1 GENERAL PARAMETERS

    GET /=/view/PostsByMonth/~/~?callback=foo        Returns "foo(<JSON>);"
                                                     instead of "<JSON>"
    GET /=/view/PostsByMonth/~/~?var=foo             Returns "foo=<JSON>;"
                                                     instead of "<JSON>"

    GET /=/view/Blah?user=agentzh.Public             Per-request-login
    GET /=/view/Blah?session=23EC98F2-F1A...         Specify the session

=head1 Path Suffixes

    GET /=/model.json           Get model list in JSON format (the default)
    GET /=/model.yaml           ditto, but in YAML format
    GET /=/model.yml            .yml is an alias for .yaml

=head1 ROLE API

=over

=item Role lists

    GET /=/role             Get the role list
    DELETE /=/role          Delete all roles (except built-in ones)

=item Roles

    GET /=/role/MyRole           Get the info for the "MyRole" role
    POST /=/role/Reader          Create an anoymous role named "Reader"
    { description:"My Role",
      login:"anonymous" }

    POST /=/role/Poster                        Create a "Poster" role
    { description:"Article Poster",            which can ony
      login:"password",                        login via passwords
      password:"encrypted password"
    }

=item ACL rules for a role

    GET /=/role/MyRole/~/~              Get all the ACL rules for MyRole
    GET /=/role/MyRole/method/GET       Filter out ACL rules with GET method
                                        only
    POST /=/role/MyRole/~/~             Allow MyRole to insert new rows into
    { method:"POST", "/=/model/Post" }  the Post model

    PUT /=/role/MyRole/id/5              Modify the ACL rule with id 5
    { method:"PUT" }

    DELETE /=/role/MyRole/method/DELETE  Banned delete operations from MyRole
    DELETE /=/role/MyRole/~/~            Delete all the ACL rules for MyRole

=back

=head1 FEED API

    POST /=/feed/Post,                   Create a feed named "Post" using the
    { "description":"My feed",           RecentPosts view
      "author":"Me","copyright":"",
      "language":"en","title":"Craps",
      "view":"RecentPosts",
      "link":"http://blog.foo.com",
      "logo":"http://foo.com/me.jpg",
    }

    GET /=/feed/Post                    Read info for the Post feed back

    PUT /=/feed/Post                    Update attributes of the Post feed
    {"author":"New author",
     "link":"http://new.home"}

    GET /=/feed/Post/~/~                Get the RSS 2.0 feed in XML

    DELETE /=/feed/Post                 Remove the Post feed
    DELETE /=/feed                      Remove all the feeds

=head1 CAPTCHA API

=over

=item Admin Setup

    POST /=/role/Commenter              Create a CommentPoster role
    { description:"Comment Poster",
      login:"captcha" }

    POST /=/role/Comment/~/~            Assign some permissions to it

    { method:"POST",
      url:"/=/model/Comment/~/~" }

=item Use in clients

    GET /=/captcha/id                   Get a captcha ID
    GET /=/captcha/id/<ID>              Get the captcha image

    POST /=/model/Comment/~/~?user=account.Commenter&captcha=<ID>:<solution>
                                        Use the captcha ID and solution
                                        to do the permitted action

=back

=head1 AUTHOR

Agent Zhang (agentzh) C<< <agentzh at yahoo.cn> >>.

=head1 SEE ALSO

L<OpenResty::Spec::REST>, L<OpenResty>.

