[[TOC]]

= S3 RESTful API =

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

  * see also [wiki:S3XRC]

'''Important to know:'''

  * In native '''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 always addressed separately
== Basic URL Syntax ==

   '''Parts in { } are optional, [ ] indicate alternatives'''

The basic '''URL format''' is:

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

  ||Item||Explanation||Example||
  ||'''path'''||the domain and path of the Eden server||demo.sahanafoundation.org/eden||
  ||'''prefix'''||the '''application prefix'''||''rms'' (=Request Management System)||
  ||'''name'''||the '''resource name'''||''req'' (=Requests)||
  ||'''arguments'''||any '''method arguments'''|| ||
  ||'''query'''||the 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:

  ||'''Operator'''||'''Method'''||'''Comments||
  ||!__eq||equal, ==||can be omitted||
  ||!__ne||not equal, !=|| ||
  ||!__lt||less than, <||numeric and date types only||
  ||!__le||less than or equal, <=||numeric and date types only||
  ||!__gt||greater than, >||numeric and date types only||
  ||!__ge||greater than or equal, >=||numeric and date types only||
  ||!__like||like, LIKE(%value%)||string/text types only||
  ||!__unlike||not like, NOT LIKE(%value%)||string/text types only||
  ||!__in||containment, contains(value)||list types only||
  ||!__ex||negative 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 ==

  '''in interactive formats (e.g. HTML):'''
  * A GET without method and no record ID results in a '''list''' view of the resource
  * A GET without method but with a record ID results in a '''read''' view of this record. If the user is permitted to update the addressed record, an '''update''' form returned instead
  * you may specify a '''method''' in the method argument list, e.g. '''create''' (=create new record), '''read''' (=view this record), '''update''' (=update this record) or '''delete''' (=delete this record), all of which are returning a form
  * some resources support other methods, e.g. '''search_simple''' to perform a simple string search (currently supported by the pr/person and hms/hospital resources)

  '''in non-interactive formats (e.g. XML):'''
  * '''method''' arguments work like in interactive formats, except they expect the data in the request body in the respective format
  * all records addressed by the URL are returned in the respective format, there is no difference between (single-record-)"read" and (multi-record-)"list" view
  * XLS and PDF format work read-only (create/update/delete being ignored)

== POST Method ==

  '''in interactive formats:'''
  * performs the respective '''method''' (if specified in the request)
  * expects the formdata as multi-part request body

  '''in non-interactive formats:'''
  * see PUT

== PUT Method ==

  '''in interactive formats:'''
  * see POST

  '''in non-interactive formats:'''
  * attempts to create/update records in a resource with the data from the request body (must be in the specified format)
  * records being matched by the UIDs specified in the data rather than those in the request

== DELETE Method ==

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

== Main Resources ==

  ||'''Application'''||'''Prefix'''||'''Resource'''||'''Resource Name'''||'''URL'''||'''Formats'''||
  ||Person Registry||pr||Persons||person||/pr/person||XML, JSON, PFIF, RSS, XLS, PDF||
  ||Person Registry||pr||Groups||group||/pr/group||XML, JSON, RSS, XLS, PDF||
  ||Map||gis||Locations||location||/gis/location||XML, JSON, GeoRSS, KML, GPX, RSS, XLS, PDF||
  ||Organization Registry||org||Organisations||organisation||/org/organisation||XML, JSON, RSS, XLS, PDF||
  ||Organization Registry||org||Offices||office||/org/office||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||Organization Registry||org||Projects||project||/org_project||XML, JSON, RSS, XLS, PDF||
  ||Hospital Management System||hms||Hospitals||hospital||/hms/hospital||XML, JSON, KML, GeoRSS, RSS, XLS, PDF, HAVE||
  ||Shelter Registry||cr||Shelters||shelter||/cr/shelter||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||DVI||dvi||Dead Body Recovery Requests||recreq||/dvi/recreq||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||DVI||dvi||Dead Body Files||body||/dvi/body||XML, JSON, RSS, XLS, PDF||
  ||Incident Report System||irs||Incident Messages||incident||/irs/incident||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||Incident Report System||irs||Incident Reports||ireport||/irs/ireport||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||Incident Report System||irs||Impact Assessments||iassessment||/irs/iassessment||XML, JSON, RSS, XLS, PDF||
  ||Rapid Assessment Tool||rat||Assessments||assessment||/rat/assessment||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
  ||Request Management System||rms||Requests||req||/rms/req||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||

== URL Examples ==

  * [GET] http://test.sahanafoundation.org/eden/pr/person
  * [GET|POST] http://test.sahanafoundation.org/eden/pr/person/create
  * [GET|POST|DELETE] http://test.sahanafoundation.org/eden/pr/person/1
  * [GET|POST|PUT|DELETE] http://test.sahanafoundation.org/eden/pr/person.xml
  * [GET|PUT] http://test.sahanafoundation.org/eden/pr/person.rss
  * [GET|PUT|DELETE] http://test.sahanafoundation.org/eden/pr/person/1.pfif
  * [GET|PUT|DELETE] http://test.sahanafoundation.org/eden/pr/person/1.json
  * [GET|DELETE] http://test.sahanafoundation.org/eden/pr/person.json?person.name__like=Fran
  * [GET|DELETE] http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com

== XML/JSON Format ==

  * see [wiki:S3XML]