[[TOC]]
= S3 RESTful API =

The S3 framework provides a generic RESTful API for many of the Eden data resources.

  * [wiki:S3XRC]

See also:

  - [wiki:S3XRC/RESTfulAPI/s3_rest_controller s3_rest_controller()]


== URL Syntax ==

   * see [wiki:S3XRC/RESTfulAPI/URLFormat URL Format]

== Standard Methods ==

'''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

=== GET ===

==== 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 ===

==== 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 ===

==== 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 ===

  * 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||

== XML/JSON Format ==

  * see [wiki:S3XML]

----

DeveloperGuidelines