Changes between Initial Version and Version 1 of REST_API


Ignore:
Timestamp:
10/13/10 22:29:26 (11 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • REST_API

    v1 v1  
     1[[TOC]]
     2
     3= S3 RESTful API =
     4
     5  * see also [wiki:S3XRC]
     6
     7== Basic URL Syntax ==
     8
     9   '''Parts in { } are optional, [ ] indicate alternatives'''
     10
     11The basic '''URL format''' is:
     12
     13  !http://<'''path'''>/<'''prefix'''>/<'''name'''>{/<'''arguments'''>}{?<'''query'''>}
     14
     15  ||Item||Explanation||Example||
     16  ||'''path'''||the domain and path of the Eden server||demo.sahanafoundation.org/eden||
     17  ||'''prefix'''||the '''application prefix'''||''rms'' (=Request Management System)||
     18  ||'''name'''||the '''resource name'''||''req'' (=Requests)||
     19  ||'''arguments'''||any '''method arguments'''|| ||
     20  ||'''query'''||the resource '''query'''|| ||
     21
     22The data format is specified as file extension to either the '''resource name''' or any of the '''method arguments''', e.g.:
     23
     24  !http://demo.sahanafoundation.org/rms/req '''.xml'''
     25
     26If multiple data format extensions are specified, the rightmost applies. Any extension can be overridden by the '''format''' parameter in the '''query''':
     27
     28  !http://demo.sahanafoundation.org/rms/req ?'''format=json'''
     29
     30== Method Arguments ==
     31
     32The '''method argument''' list uses the following syntax:
     33
     34  { /'''id''' }{ / [ '''method''' | '''component''' { /'''component_id'''  } { /'''method''' } ] }
     35
     36where:
     37
     38  * '''id''' is a record ID in the main resource
     39  * '''component''' is the name of a subresource (e.g. ''address'' is a subresource of ''person'')
     40  * '''component_id''' is the record ID in the subresource
     41  * '''method''' is a URL method (only in GET/POST requests, e.g. "create", "read", "update")
     42
     43== Query Syntax ==
     44
     45The basic query format is: '''resource'''.'''field'''{'''operator'''}='''value'''
     46
     47  * '''resource''' is the name of the resource or component (without prefix) or the name of the context
     48  * '''field''' is the name of the field to be tested
     49  * '''operator''' is the operator
     50  * '''value''' is the value or a comma-separated list of values to test against (a comma will be treated as OR)
     51
     52Supported operators:
     53
     54  ||'''Operator'''||'''Method'''||'''Comments||
     55  ||!__eq||equal, ==||can be omitted||
     56  ||!__ne||not equal, !=|| ||
     57  ||!__lt||less than, <||numeric and date types only||
     58  ||!__le||less than or equal, <=||numeric and date types only||
     59  ||!__gt||greater than, >||numeric and date types only||
     60  ||!__ge||greater than or equal, >=||numeric and date types only||
     61  ||!__like||like, LIKE(%value%)||string/text types only||
     62  ||!__unlike||not like, NOT LIKE(%value%)||string/text types only||
     63  ||!__in||containment, contains(value)||list types only||
     64  ||!__ex||negative containment, not contains(value)||list types only||
     65
     66=== Examples ===
     67
     68  * Testing a field in the main resource:
     69{{{
     70  /pr/person?person.first_name__like=Miriam
     71}}}
     72
     73  * Testing a field in a subresource (component):
     74{{{
     75  /pr/person?address.city__like=Oslo
     76}}}
     77
     78=== Context Queries ===
     79
     80  * Testing a field in a referenced resource
     81  * Context must be specified like:
     82
     83  '''context.'''name'''={'''component'''.}'''field'''
     84
     85  where:
     86
     87  * '''name''' is a name for the context (as reference for subsequent queries)
     88  * '''component''' is the name of the component resource (without prefix)
     89  * '''field''' is the field name of the foreign key field
     90
     91{{{
     92   /pr/person?context.location=address.location_id&location.lat__gt=0
     93}}}
     94
     95== GET Methods ==
     96
     97  '''in interactive formats (e.g. HTML):'''
     98  * A GET without method and no record ID results in a '''list''' view of the resource
     99  * 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
     100  * 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
     101  * 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)
     102
     103  '''in non-interactive formats (e.g. XML):'''
     104  * '''method''' arguments work like in interactive formats, except they expect the data in the request body in the respective format
     105  * 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
     106  * XLS and PDF format work read-only (create/update/delete being ignored)
     107
     108== POST Method ==
     109
     110  '''in interactive formats:'''
     111  * performs the respective '''method''' (if specified in the request)
     112  * expects the formdata as multi-part request body
     113
     114  '''in non-interactive formats:'''
     115  * see PUT
     116
     117== PUT Method ==
     118
     119  '''in interactive formats:'''
     120  * see POST
     121
     122  '''in non-interactive formats:'''
     123  * attempts to create/update records in a resource with the data from the request body (must be in the specified format)
     124  * records being matched by the UIDs specified in the data rather than those in the request
     125
     126== DELETE Method ==
     127
     128  * deletes those of the addressed records which are deletable by the current user
     129
     130== Main Resources ==
     131
     132  ||'''Application'''||'''Prefix'''||'''Resource'''||'''Resource Name'''||'''URL'''||'''Formats'''||
     133  ||Person Registry||pr||Persons||person||/pr/person||XML, JSON, PFIF, RSS, XLS, PDF||
     134  ||Person Registry||pr||Groups||group||/pr/group||XML, JSON, RSS, XLS, PDF||
     135  ||Map||gis||Locations||location||/gis/location||XML, JSON, GeoRSS, KML, GPX, RSS, XLS, PDF||
     136  ||Organization Registry||org||Organisations||organisation||/org/organisation||XML, JSON, RSS, XLS, PDF||
     137  ||Organization Registry||org||Offices||office||/org/office||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     138  ||Organization Registry||org||Projects||project||/org_project||XML, JSON, RSS, XLS, PDF||
     139  ||Hospital Management System||hms||Hospitals||hospital||/hms/hospital||XML, JSON, KML, GeoRSS, RSS, XLS, PDF, HAVE||
     140  ||Shelter Registry||cr||Shelters||shelter||/cr/shelter||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     141  ||DVI||dvi||Dead Body Recovery Requests||recreq||/dvi/recreq||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     142  ||DVI||dvi||Dead Body Files||body||/dvi/body||XML, JSON, RSS, XLS, PDF||
     143  ||Incident Report System||irs||Incident Messages||incident||/irs/incident||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     144  ||Incident Report System||irs||Incident Reports||ireport||/irs/ireport||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     145  ||Incident Report System||irs||Impact Assessments||iassessment||/irs/iassessment||XML, JSON, RSS, XLS, PDF||
     146  ||Rapid Assessment Tool||rat||Assessments||assessment||/rat/assessment||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     147  ||Request Management System||rms||Requests||req||/rms/req||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     148