RESTful FaZend

published by yegor256 on Feb 8, 2011

This is a draft of RESTful interface, please submit your suggestions here or in our Google Group thread.

All HTTP 1.1 requests are to be sent to port 80. All requests have to be authorized with BASIC or DIGEST authorization schema. You should use the same login/password as at www.fazend.com.

Output is formatted according to Accept HTTP request header. We support the following content types: text/plain, text/html (default), application/json, application/xml. Actual content type returned is specified in Content-Type HTTP response header.

Points of access and operations are: 

    front.rest.fazend.com:
        GET /projects
        POST /projects/create
        GET /project/ABC
            POST /archive
            GET or PUT /authz
            GET or PUT /passwd
            GET or PUT /trac
            GET or PUT /ci
    trac.rest.fazend.com:
        GET /project/ABC
            GET /size
            POST /sqlite
    svn.rest.fazend.com:
        GET /project/ABC
            GET /size
            POST /svnadmin
            POST /svnsync
    ci.rest.fazend.com:
        GET /project/ABC
            GET /size
            GET /config

A full-scale example

You can execute svnadmin verify command on your Subversion repository via this HTTP request (it's Linux shell): 

    $ telnet svn.rest.fazend.com 80
    Trying 173.203.78.110...
    Connected to svn.rest.fazend.com.
    Escape character is '^]'.
    POST /project/my-project/svnadmin HTTP/1.1
    Host: svn.rest.fazend.com
    Content-Length: 6

    verify
    HTTP/1.1 200 OK
    Content-Length: 25
    Content-Type: text/plain
    * Verified revision 123.

This is what just happened in the example:

  1. We POST-ed 6-letter text "verify to /project/my-project/svnadmin at svn.rest.fazend.com;
  2. The server executed svnadmin verify $REPO command, where $REPO was substituted with a real location of our repository at the server;
  3. svnadmin responded with * Verified revision 123.\n text;
  4. We received 25-letter text back in HTTP/1.1 response, formatted as plain/text.

Detailed specification

Access point Method Input Output
front.rest.fazend.com
/projects GET — List of project names
/projects/create POST project name Response body is empty, HTTP status is 201, response header Location contains /projects/ABC. Status is 400 if project name is wrongly formatted. Status is 409 if a project with this name already exists.
/projects/ABC GET — Response body contains associative array of links to project sub-resources, HTTP status is 200. Status is 400 if project name is wrongly formatted. Status is 403 if a project exists, but belongs to another user.

to be continued...

read all articles...