Changes between Version 32 and Version 33 of REST_API


Ignore:
Timestamp:
06/11/14 09:51:34 (7 years ago)
Author:
MattS
Comment:

Clearing old content - leave redirect link for now to avoid broken links to this page

Legend:

Unmodified
Added
Removed
Modified
  • REST_API

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