Changes between Initial Version and Version 1 of REST_API

Timestamp:

10/13/10 22:29:26 (14 years ago)

Author:

Dominic König

Comment:

--

REST_API

@@ +1 @@
+[[TOC]]
+
+= S3 RESTful API =
+
+  * see also [wiki:S3XRC]
+
+== 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||
+