wiki:REST_API

Version 30 (modified by Dominic König, 14 years ago) ( diff )

--

Table of Contents

  1. Basic URL Syntax
  2. Method Arguments
  3. Query Syntax
    1. Examples
    2. Context Queries
  4. GET Methods
      1. Interactive Formats
      2. Non-interactive formats
  5. POST Method
      1. Interactive Formats
      2. Non-interactive Formats
  6. PUT Method
      1. Interactive formats
      2. Non-interactive formats
  7. DELETE Method
  8. Main Resources
  9. URL Examples
      1. Interactive (HTML) Format
      2. Non-interactive Formats
      3. URL Method
      4. Record ID
      5. Record UID
      6. URL Queries
  10. XML/JSON Format

S3 RESTful API

The S3 framework provides a generic RESTful API for many of the Eden data resources.

Important to know:

  • In XML and JSON, data resources are always exported/imported in compound with all their subresources and referenced resources.
  • In all other formats, main resources and subresources are addressed separately

Basic URL Syntax

Parts in { } are optional, [ ] indicate alternatives

The basic URL format is:

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

ItemExplanationExample
paththe domain and path of the Eden serverdemo.sahanafoundation.org/eden
prefixthe application prefixrms (=Request Management System)
namethe resource namereq (=Requests)
argumentsany method arguments
querythe resource query

The data format is specified as file extension to either the resource name or any of the method arguments, e.g.:

http://demo.sahanafoundation.org/rms/req .xml

If multiple data format extensions are specified, the rightmost applies. Any extension can be overridden by the format parameter in the query:

http://demo.sahanafoundation.org/rms/req ?format=json

Method Arguments

The method argument list uses the following syntax:

{ /id }{ / [ method | component { /component_id } { /method } ] }

where:

  • id is a record ID in the main resource
  • component is the name of a subresource (e.g. address is a subresource of person)
  • component_id is the record ID in the subresource
  • method is a URL method (only in GET/POST requests, e.g. "create", "read", "update")

Query Syntax

The basic query format is: resource.field{operator}=value

  • resource is the name of the resource or component (without prefix) or the name of the context
  • field is the name of the field to be tested
  • operator is the operator
  • value is the value or a comma-separated list of values to test against (a comma will be treated as OR)

Supported operators:

OperatorMethodComments
__eqequal, =can be omitted
__nenot equal, =||
__ltless than, <numeric and date types only
__leless than or equal, <numeric and date types only
__gtgreater than, >numeric and date types only
__gegreater than or equal, >numeric and date types only
__likelike, LIKE(%value%)string/text types only
__unlikenot like, NOT LIKE(%value%)string/text types only
__incontainment, contains(value)list types only
__exnegative containment, not contains(value)list types only

Examples

  • Testing a field in the main resource: 
      /pr/person?person.first_name__like=Miriam
  • Testing a field in a subresource (component): 
      /pr/person?address.city__like=Oslo

Context Queries

  • Testing a field in a referenced resource
  • Context must be specified like:

context.name={component.}field

where:

  • name is a name for the context (as reference for subsequent queries)
  • component is the name of the component resource (without prefix)
  • field is the field name of the foreign key field 
   /pr/person?context.location=address.location_id&location.lat__gt=0

GET Methods

Interactive Formats

  • without method:
    • if no record ID/UID in the URL: list view of the resource
    • with a record ID/UID in the URL: read view of the specified record (if the user is permitted to update the record, an update form returned instead)
  • with method 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 form for the specified records
  • some resources support other (custom) methods, e.g.
    • search_simple returns a form for simple string search in the resource

Non-interactive formats

  • without method:
    • returns a list of all matching records in the specified format
  • with method in the URL:
    • method create or update imports data into the resource from the specified data source:
      • ?filename= variable to specify a local file (on the server)
      • ?fetchurl= variable to specify a source URL
      • with format extension .url data are imported directly from the URL
      • if none of the above is specified, data are imported from the request body
    • method read returns a the specified records in the requested format
    • method delete deletes the specified records
  • XLS and PDF format work read-only (create/update/delete being ignored)

POST Method

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

  • see PUT

PUT Method

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 Method

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

Main Resources

ApplicationPrefixResourceResource NameURLFormats
Person RegistryprPersonsperson/pr/personXML, JSON, PFIF, RSS, XLS, PDF
Person RegistryprGroupsgroup/pr/groupXML, JSON, RSS, XLS, PDF
MapgisLocationslocation/gis/locationXML, JSON, GeoRSS, KML, GPX, RSS, XLS, PDF
Organization RegistryorgOrganisationsorganisation/org/organisationXML, JSON, RSS, XLS, PDF
Organization RegistryorgOfficesoffice/org/officeXML, JSON, KML, GeoRSS, RSS, XLS, PDF
Organization RegistryorgProjectsproject/org_projectXML, JSON, RSS, XLS, PDF
Hospital Management SystemhmsHospitalshospital/hms/hospitalXML, JSON, KML, GeoRSS, RSS, XLS, PDF, HAVE
Shelter RegistrycrSheltersshelter/cr/shelterXML, JSON, KML, GeoRSS, RSS, XLS, PDF
DVIdviDead Body Recovery Requestsrecreq/dvi/recreqXML, JSON, KML, GeoRSS, RSS, XLS, PDF
DVIdviDead Body Filesbody/dvi/bodyXML, JSON, RSS, XLS, PDF
Incident Report SystemirsIncident Messagesincident/irs/incidentXML, JSON, KML, GeoRSS, RSS, XLS, PDF
Incident Report SystemirsIncident Reportsireport/irs/ireportXML, JSON, KML, GeoRSS, RSS, XLS, PDF
Incident Report SystemirsImpact Assessmentsiassessment/irs/iassessmentXML, JSON, RSS, XLS, PDF
Rapid Assessment ToolratAssessmentsassessment/rat/assessmentXML, JSON, KML, GeoRSS, RSS, XLS, PDF
Request Management SystemrmsRequestsreq/rms/reqXML, JSON, KML, GeoRSS, RSS, XLS, PDF

URL Examples

Interactive (HTML) Format

Non-interactive Formats

URL Method

Record ID

Record UID

URL Queries

XML/JSON Format

Note: See TracWiki for help on using the wiki.