Sahana Eden

Web Services

Web Services in Sahana Eden are implemented as a RESTful API (Application Programming Interface).

This API allows other applications to access and manipulate Sahana Eden data resources directly over the web using the HTTP protocol, which means:

  • URLs to address resources
  • HTTP requests to perform actions and transfer data
  • HTTP method verbs (GET, PUT, POST, DELETE) to specify the actions to be performed
  • HTTP status codes to report status and errors

A powerful query language is available to address particular data elements: 

/eden/pr/person?person.first_name__like=Miriam

(all person records where the first name contains "Miriam")

...or to specify method parameters: 

/eden/org/office/analyze?col=location_id&row=type&fact=name&aggregate=group_concat

(a pivot table of offices grouped by facility type vs. location)

The RESTful API uses Sahana Eden's native S3XML format for data exchange. Other XML or JSON formats are supported using on-the-fly XSLT transformation - Sahana Eden provides built-in XSLT stylesheets for a variety of XML standards (e.g. KML, EDXL-HAVE), and can also accept custom stylesheets.

URL Format

Basic URL Syntax

Example of a URL to address a resource in the Sahana Eden RESTful API: 

http://vita.sahanafoundation.org/eden/hms/hospital/1/bed_capacity/create

The basic URL format is:

(Parts in { } are optional, [ A | B ] indicates alternatives) 

http:// server / path / prefix / name { /<arguments> }{ ?<query> }

  • server (vita.sahanafoundation.org) is the server domain name
  • path (/eden) the path to the application
  • prefix (/hms) is the name (prefix) of the Sahana Eden module
  • name (/hospital) is the resource name

The <arguments> list consists of: 

{ /id }{ / [ method | component { /component_id } { /method } ] } {.format}
  • id (/1) is a record ID in the master table of the resource
  • component (/bed_capacity) is a component name
  • component_id is a record ID in the component
  • method (/create) is a method of the resource
  • format specifies the requested data format (e.g.: ".xml" for S3XML)

For the <query> syntax, see the following section.

Basic Query Format

Example of a URL query: 

?hospital.name__like=Example%20Hospital

...as part the complete URL: 

http://vita.sahanafoundation.org/eden/hms/hospital?hospital.name__like=Example%20Hospital
The basic query format is: 

?resource.{foreign key$}field{operator}=value(s)

  • resource (hospital) is the name of the component, followed by a period (.)
  • foreign key is the name of the foreign key field followed by a dollar sign (to filter against a value in the table referenced by this foreign key)
  • field (name) is the name of the field in the target table
  • operator (__like) is the operator
  • value(s) (Example%20Hospital) is the value or a comma-separated list of values to test against (a comma will be treated as an OR)
Note that special characters in values must be properly URL-encoded (the %20 in this example stands for a blank).

Supported operators:

Operator Method Comments
__eq equal, = can be omitted
__ne not equal, !=
__lt less than, < numeric and date/time types only
__le less than or equal, <= numeric and date/time types only
__gt greater than, > numeric and date/time types only
__ge greater than or equal, >= numeric and date/time types only
__like wildcard comparison, LIKE(%value%) string/text types only
__unlike negative wildcard comparison, NOT LIKE(%value%) string/text types only
__in containment, contains(value) list types only
__ex negative containment, excludes(value) list types only

Other Queries

Boundary Box Queries

For resources with location references (e.g. Hospitals), you can use boundary box queries to select records. The general format of the query variable is: 

?bbox=minLon,minLat,maxLon,maxLat

    You can also specify the foreign key field name of the location reference the query relates to (e.g. in case there are multiple location references in that resource): 

    ?bbox.FKFieldName=minLon,minLat,maxLon,maxLat

      Examples: 

      /hms/hospital?bbox=123,13.5,124,13.7

      /hms/hospital?bbox.location_id=123,13.5,124,13.7

      URL Examples

      Interactive (HTML) Format

      All "person" records in the Person Registry module (pr): 

      http://localhost:8000/eden/pr/person

      Non-interactive Formats

      All "person" records in the Person Registry module (pr), in other data formats: 

      http://localhost:8000/eden/pr/person.pdf
http://localhost:8000/eden/pr/person.rss
http://localhost:8000/eden/pr/person.xml

      Record by ID 

      http://localhost:8000/eden/pr/person/1
http://localhost:8000/eden/pr/person/1.pfif
http://localhost:8000/eden/pr/person/1.xml

      Record by UUID 

      http://localhost:8000/eden/pr/person?person.uuid= urn:uuid:839bab5a-a401-4be3-8616-27fbc1810ef4

      URL Queries 

      http://localhost:8000/eden/pr/person?person.id=1,2,3

http://localhost:8000/eden/org/office?office.type=None,1,2&office.obsolete=False

http://localhost:8000/eden/org/office?office.modified_on__gt=20110926T10:00:00

      Note that in URL queries, date/time values must be in UTC and use the ISO-8601 combined format YYYMMDDThh:mm:ss.

      Standard Methods

      Standard methods include:

      • interactive create, read, update and delete (CRUD) including list views
      • data export/import in various formats, including on-the-fly transformation

      Note:

      • in XML and JSON, resources are always exported/imported including all their components and referenced resources.
      • in all other formats, the components need to be addressed separately

      GET

      Interactive Formats

      Interactive formats are HTML (Extension ".html"), or PLAIN (Extension ".plain"). If no format extension is specified, HTML format is assumed.

      • without method specified in the URL:
        • if no record ID in the URL: list view of the resource
        • with a record ID in the URL: read view of the specified record (if the user is permitted to update the record, an update form returned instead)

      Example: read view of the person record #1: 

      http://localhost:8000/eden/pr/person/1
      • with method specified in the URL:
        • method create returns a create-form
        • method read returns a view of the specified record (other than with blank method, no update form is returned in this case)
        • method update returns an update form for the specified record
        • method delete returns a delete confirmation form together with a list of the specified records (if there is exactly one record identified by its ID in the URL, then the record will be deleted instead of a form being returned, see POST)

      Example: create form for a new person record: 

      http://localhost:8000/eden/pr/person/create
      • some resources support other methods, e.g.
        • search returns a search form for the resource

      Example: search for a person by name or ID: 

      http://localhost:8000/eden/pr/person/search

      Non-interactive formats

      Any format extension that is not listed under the interactive formats, is treated as non-interactive.

      • without method in the URL:
        • returns all matching records in the specified format

      Example: all person records the user is allowed to read, in S3XML format: 

      GET http://localhost:8000/eden/pr/person.xml
      • with method in the URL:
        • method create or update returns a schema document of the resource
        • method create or update together with a source imports the data into the specified resource (see chapter S3XML)
        • method options returns a field options document of the resource
        • other methods are not supported

      Example: get a schema document of the person resource: 

      GET http://localhost:8000/eden/pr/person/create.xml
      • XLS and PDF formats work read-only (create/update/delete being ignored)

      POST

      Interactive Formats

      • performs the respective method (if specified in the request)
        • method create creates a new record
        • method update updates the specified record
        • method delete deletes the specified record
      • expects the form data as multi-part request body

      Non-interactive Formats

      • enters an interactive review of the source data before importing the data into the resource

      PUT

      Interactive formats

      • see POST

      Non-interactive formats

      • import data from the request body (which must be in the specified format) into the resource
      • records being matched by the UIDs specified in the data, while any record IDs in the URL restrict the selection

      DELETE

      • deletes those of the addressed records which are deletable by the current user

      Authorization

      It is possible to access privileged resources by providing the username/password within each request, rather than the usual method of having the login stored within the session.

      The RESTful API supports HTTP Basic Authentication (http://en.wikipedia.org/wiki/Basic_access_authentication).

      Note: for some command-line tools like wget or RESTClient you might need to additionally activate an option for pre-emptive authentication (unsolicited sending of credentials). E.g. for wget, use the --auth-no-challenge option.

      AJAX Examples

      Here some examples how to add the HTTP Basic Authentication header to AJAX requests: 

      function make_base_auth(user, password) {
 var tok = user + ':' + pass;
 var hash = Base64.encode(tok);
 return 'Basic ' + hash;
}

var auth = make_basic_auth('username@example.com', 'password');
var url = 'http://host.domain/eden/controller/function?vars';

// RAW
request = new XMLHttpRequest();
request.setRequestHeader('Authorization', auth);
request.open('PUT', url, true); // async=true
request.send(bodyContent);

// ExtJS
Ext.Ajax.request({
    url : url,
    method : 'GET',
    headers : { Authorization : auth }
});

// jQuery
$.ajax({
    url : url,
    method : 'GET',
    beforeSend : function(req) {
        req.setRequestHeader('Authorization', auth);
    }
});

      Error Handling

      The HTTP status code in the response indicates the success or failure of a request:

      Status Code Cause  Response Body
       200 OK Success results or JSON message
      400 BAD REQUEST Syntax error or method not supported for the specified resource
      		JSON message
      401 UNAUTHORIZED Authorization required Clear text error
      403 FORBIDDEN Insufficient permissions Clear text error
      404 NOT FOUND Non-existent Resource Clear text error
      50x Unrecoverable internal error Ticket issued or clear text error
       

      Where a JSON message is returned, it has the following structure: 
        {
    success= "True" | "False",
    statuscode = "XXX",
    message = "clear text error message",
    tree = {
      /* element tree */
    }
  }

      If there was an input element tree and it contained any errors, a subtree with the invalid elements will be added to the JSON message ("tree"). This subtree is expressed in JSON Format. Invalid elements will have an additional @error attribute containing a clear-text error desription.

      Skipping invalid records at import:

      By default, an import request will be rolled back (completely) and an HTTP 400 BAD REQUEST error be returned if the source contains any invalid data.

      You can override this behavior by using the ignore_errors URL variable (?ignore_errors=True). Invalid records will then be skipped, while the valid records will be committed to the database and the request returns a HTTP 200 OK. The JSON message in the response body would however contain the error message and the element tree with the invalid elements.

      Note that ignore_errors applies to Validation Errors only. Any other type of error (e.g. XML syntax error) will be handled as usual (=rollback + error message).

      The ignore_errors option is meant for "dirty" data, e.g. cases where you need to import from a source but do not have permission and/or means to clean it up before import. In all other cases, where possible, you should avoid ignore_errors and rather sanitize the source.

      S3XML On-the-fly Transformation

      The Sahana Eden RESTful API can perform XSLT transformation of XML sources into the S3XML format on-the-fly when exporting or importing data.

       


      The XSLT stylesheets to use for this transformation can be:

      • a static file on the server or a web URL
      • a file attached to the request (at import)
      • an integrated stylesheet of Eden (folder static/formats)

      Note:

      • You cannot use the .xml or .json extension if the source is to be transformed. By these extensions, the interface assumes the source is already S3XML.
      • Non-XML formats such as PDF or XLS do not support on-the-fly transformation.

      Integrated Transformation Stylesheets

      Sahana Eden provides a number of internal XSLT stylesheets for various formats. These will be automatically used if no other stylesheet is specified (fallback). The internal stylesheets reside in:

      • static/formats/<format>/export.xsl to transform S3XML into another format
      • static/formats/<format>/import.xsl to transform another format into S3XML

      Example:

      • static/formats/have/import.xsl transforms EDXL-HAVE (*.have) into S3XML
      • static/formats/have/export.xsl transforms S3XML into EDXL-HAVE

      XSLT Stylesheets on the Server

      You can use the URL variable transform to specify a transformation stylesheet at a file system location on the server, e.g.: 

      http://127.0.0.1:8000/eden/pr/person.pfif?transform=/home/dominic/stylesheets/pfif.xsl

      ...or at another location on the web,e.g.: 

      http://127.0.0.1:8000/eden/pr/person.rss?transform=http://pub.nursix.org/eden/formats/rss.xsl

      If you use transform to specify the stylesheet location explicitly, any existing internal stylesheet for the format extension would not be used.

      Note:

      • the Eden web server must be permitted to access the stylesheet without authentication
      • the request must not use ".xml" as data format extension, otherwise no transformation will be performed at all (transform would be ignored then)

      This feature is especially useful to create custom feeds to integrate into remote sites, e.g. RSS:

      • create your own rss.xsl to transform S3XML into RSS
      • place it on a public (e.g. your own) web server, e.g.: 
      http://www.example.org/eden-access/rss.xsl
      • provide a feed link to Eden resources using your RSS stylesheet: 
        http://edensite.org/eden/hms/hospital.rss?transform=http://www.mysite.org/eden-access/rss.xsl

      This does work with any XML format, e.g. KML - if you wanted to provide a map rather than a feed link.

      Attached XSLT Stylesheets

      For data import, an XSLT stylesheet to transform foreign XML into S3XML can be attached to the request.

      The filename of the attached stylesheet is expected to be <resourcename>.xsl, where <resourcename> is the name of the target resource (without module prefix, e.g. person or hospital).

      Note:

      • document(), xsl:include and xsl:import will need absolute paths in this case (safer to avoid these)