Changes between Version 1 and Version 2 of S3/S3REST

Timestamp:

10/22/10 10:50:19 (14 years ago)

Author:

Dominic König

Comment:

--

S3/S3REST

@@ +1 @@
+[[TOC]]
 = S3 RESTful API =
 
+The S3 framework provides a generic RESTful API for many of the Eden data resources.
+
   * [wiki:S3XRC]
 
+
+'''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'''>}
+
+  ||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 ==
+
+==== 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 ==
+
+  ||'''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 ==
+
+==== Interactive (HTML) Format ====
+
+  * http://test.sahanafoundation.org/eden/pr/person
+
+==== Non-interactive Formats ====
+
+  * http://test.sahanafoundation.org/eden/pr/person.pdf
+  * http://test.sahanafoundation.org/eden/pr/person.rss
+  * http://test.sahanafoundation.org/eden/pr/person.xml
+
+==== URL Method ====
+
+  * http://test.sahanafoundation.org/eden/pr/person/create
+
+==== Record ID ====
+
+  * http://test.sahanafoundation.org/eden/pr/person/1
+
+  * http://test.sahanafoundation.org/eden/pr/person/1.pfif
+  * http://test.sahanafoundation.org/eden/pr/person/1.json
+
+==== Record UID ====
+
+  * http://test.sahanafoundation.org/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac
+
+==== URL Queries ====
+
+  * http://test.sahanafoundation.org/eden/pr/person?person.id=1,2,3
+
+  * http://test.sahanafoundation.org/eden/pr/person.pfif?person.first_name__like=Dominic
+  * http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com
+
+== XML/JSON Format ==
+
+  * see [wiki:S3XML]
+
 ----