Changes between Version 1 and Version 2 of S3/S3REST


Ignore:
Timestamp:
10/22/10 10:50:19 (11 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3REST

    v1 v2  
     1[[TOC]]
    12= S3 RESTful API =
    23
     4The S3 framework provides a generic RESTful API for many of the Eden data resources.
     5
    36  * [wiki:S3XRC]
    47
     8
     9'''Important to know:'''
     10
     11  * In '''XML and JSON''', data resources are always exported/imported in compound with all their subresources and referenced resources.
     12  * In '''all other formats''', main resources and subresources are addressed separately
     13
     14== Basic URL Syntax ==
     15
     16   '''Parts in { } are optional, [ ] indicate alternatives'''
     17
     18The basic '''URL format''' is:
     19
     20  !http://<'''path'''>/<'''prefix'''>/<'''name'''>{/<'''arguments'''>}{?<'''query'''>}
     21
     22  ||Item||Explanation||Example||
     23  ||'''path'''||the domain and path of the Eden server||demo.sahanafoundation.org/eden||
     24  ||'''prefix'''||the '''application prefix'''||''rms'' (=Request Management System)||
     25  ||'''name'''||the '''resource name'''||''req'' (=Requests)||
     26  ||'''arguments'''||any '''method arguments'''|| ||
     27  ||'''query'''||the resource '''query'''|| ||
     28
     29The data format is specified as file extension to either the '''resource name''' or any of the '''method arguments''', e.g.:
     30
     31  !http://demo.sahanafoundation.org/rms/req '''.xml'''
     32
     33If multiple data format extensions are specified, the rightmost applies. Any extension can be overridden by the '''format''' parameter in the '''query''':
     34
     35  !http://demo.sahanafoundation.org/rms/req ?'''format=json'''
     36
     37== Method Arguments ==
     38
     39The '''method argument''' list uses the following syntax:
     40
     41  { /'''id''' }{ / [ '''method''' | '''component''' { /'''component_id'''  } { /'''method''' } ] }
     42
     43where:
     44
     45  * '''id''' is a record ID in the main resource
     46  * '''component''' is the name of a subresource (e.g. ''address'' is a subresource of ''person'')
     47  * '''component_id''' is the record ID in the subresource
     48  * '''method''' is a URL method (only in GET/POST requests, e.g. "create", "read", "update")
     49
     50== Query Syntax ==
     51
     52The basic query format is: '''resource'''.'''field'''{'''operator'''}='''value'''
     53
     54  * '''resource''' is the name of the resource or component (without prefix) or the name of the context
     55  * '''field''' is the name of the field to be tested
     56  * '''operator''' is the operator
     57  * '''value''' is the value or a comma-separated list of values to test against (a comma will be treated as OR)
     58
     59Supported operators:
     60
     61  ||'''Operator'''||'''Method'''||'''Comments||
     62  ||!__eq||equal, ==||can be omitted||
     63  ||!__ne||not equal, !=|| ||
     64  ||!__lt||less than, <||numeric and date types only||
     65  ||!__le||less than or equal, <=||numeric and date types only||
     66  ||!__gt||greater than, >||numeric and date types only||
     67  ||!__ge||greater than or equal, >=||numeric and date types only||
     68  ||!__like||like, LIKE(%value%)||string/text types only||
     69  ||!__unlike||not like, NOT LIKE(%value%)||string/text types only||
     70  ||!__in||containment, contains(value)||list types only||
     71  ||!__ex||negative containment, not contains(value)||list types only||
     72
     73=== Examples ===
     74
     75  * Testing a field in the main resource:
     76{{{
     77  /pr/person?person.first_name__like=Miriam
     78}}}
     79
     80  * Testing a field in a subresource (component):
     81{{{
     82  /pr/person?address.city__like=Oslo
     83}}}
     84
     85=== Context Queries ===
     86
     87  * Testing a field in a referenced resource
     88  * Context must be specified like:
     89
     90  '''context.'''name'''={'''component'''.}'''field'''
     91
     92  where:
     93
     94  * '''name''' is a name for the context (as reference for subsequent queries)
     95  * '''component''' is the name of the component resource (without prefix)
     96  * '''field''' is the field name of the foreign key field
     97
     98{{{
     99   /pr/person?context.location=address.location_id&location.lat__gt=0
     100}}}
     101
     102== GET Methods ==
     103
     104==== Interactive Formats ====
     105
     106  * without method:
     107    - if no record ID/UID in the URL: '''list''' view of the resource
     108    - 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)
     109
     110  * with '''method''' in the URL:
     111    - method '''create''' returns a create-form
     112    - method '''read''' returns a view of the specified record (other than with blank method, no update form is returned in this case)
     113    - method '''update''' returns an update form for the specified record
     114    - method '''delete''' returns a delete form for the specified records
     115
     116  * some resources support other (custom) methods, e.g.
     117    - '''search_simple''' returns a form for simple string search in the resource
     118
     119==== Non-interactive formats ====
     120
     121  * without '''method''':
     122    - returns a list of all matching records in the specified format
     123
     124  * with '''method''' in the URL:
     125    - method '''create''' or '''update''' imports data into the resource from the specified data source:
     126      * ''?filename='' variable to specify a local file (on the server)
     127      * ''?fetchurl='' variable to specify a source URL
     128      * with format extension ''.url'' data are imported directly from the URL
     129      * if none of the above is specified, data are imported from the request body
     130    - method '''read''' returns a the specified records in the requested format
     131    - method '''delete''' deletes the specified records
     132
     133  * XLS and PDF format work read-only (create/update/delete being ignored)
     134== POST Method ==
     135
     136==== Interactive Formats ====
     137
     138  * performs the respective '''method''' (if specified in the request)
     139    - method '''create''' creates a new record
     140    - method '''update''' updates the specified record
     141    - method '''delete''' deletes the specified record
     142  * expects the form data as multi-part request body
     143
     144==== Non-interactive Formats ====
     145
     146  * see PUT
     147
     148== PUT Method ==
     149
     150==== Interactive formats ====
     151
     152  * see POST
     153
     154==== Non-interactive formats ====
     155
     156  * import data from the request body (which must be in the specified format) into the resource
     157  * records being matched by the UIDs specified in the data, while any record IDs in the URL restrict the selection
     158== DELETE Method ==
     159
     160  * deletes those of the addressed records which are deletable by the current user
     161
     162== Main Resources ==
     163
     164  ||'''Application'''||'''Prefix'''||'''Resource'''||'''Resource Name'''||'''URL'''||'''Formats'''||
     165  ||Person Registry||pr||Persons||person||/pr/person||XML, JSON, PFIF, RSS, XLS, PDF||
     166  ||Person Registry||pr||Groups||group||/pr/group||XML, JSON, RSS, XLS, PDF||
     167  ||Map||gis||Locations||location||/gis/location||XML, JSON, GeoRSS, KML, GPX, RSS, XLS, PDF||
     168  ||Organization Registry||org||Organisations||organisation||/org/organisation||XML, JSON, RSS, XLS, PDF||
     169  ||Organization Registry||org||Offices||office||/org/office||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     170  ||Organization Registry||org||Projects||project||/org_project||XML, JSON, RSS, XLS, PDF||
     171  ||Hospital Management System||hms||Hospitals||hospital||/hms/hospital||XML, JSON, KML, GeoRSS, RSS, XLS, PDF, HAVE||
     172  ||Shelter Registry||cr||Shelters||shelter||/cr/shelter||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     173  ||DVI||dvi||Dead Body Recovery Requests||recreq||/dvi/recreq||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     174  ||DVI||dvi||Dead Body Files||body||/dvi/body||XML, JSON, RSS, XLS, PDF||
     175  ||Incident Report System||irs||Incident Messages||incident||/irs/incident||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     176  ||Incident Report System||irs||Incident Reports||ireport||/irs/ireport||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     177  ||Incident Report System||irs||Impact Assessments||iassessment||/irs/iassessment||XML, JSON, RSS, XLS, PDF||
     178  ||Rapid Assessment Tool||rat||Assessments||assessment||/rat/assessment||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     179  ||Request Management System||rms||Requests||req||/rms/req||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
     180
     181== URL Examples ==
     182
     183==== Interactive (HTML) Format ====
     184
     185  * http://test.sahanafoundation.org/eden/pr/person
     186
     187==== Non-interactive Formats ====
     188
     189  * http://test.sahanafoundation.org/eden/pr/person.pdf
     190  * http://test.sahanafoundation.org/eden/pr/person.rss
     191  * http://test.sahanafoundation.org/eden/pr/person.xml
     192
     193==== URL Method ====
     194
     195  * http://test.sahanafoundation.org/eden/pr/person/create
     196
     197==== Record ID ====
     198
     199  * http://test.sahanafoundation.org/eden/pr/person/1
     200
     201  * http://test.sahanafoundation.org/eden/pr/person/1.pfif
     202  * http://test.sahanafoundation.org/eden/pr/person/1.json
     203
     204==== Record UID ====
     205
     206  * http://test.sahanafoundation.org/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac
     207
     208==== URL Queries ====
     209
     210  * http://test.sahanafoundation.org/eden/pr/person?person.id=1,2,3
     211
     212  * http://test.sahanafoundation.org/eden/pr/person.pfif?person.first_name__like=Dominic
     213  * http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com
     214
     215== XML/JSON Format ==
     216
     217  * see [wiki:S3XML]
     218
    5219----
    6220