[[TOC]]
[wiki:S3XRC] | [wiki:S3XRC/RESTfulAPI S3 RESTful API] | Methods
= S3 RESTful 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

  - interactive create, read, update and delete (CRUD) including list views
  - non-interactive data export/import

== Standard Methods ==

  * see also: [wiki:S3XRC/RESTfulAPI/URLFormat URL Format]
=== 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)

  ''Example:'' '''read''' view of pr_person !#1 (or an '''update''' form if the user is permitted to update this record)
  {{{
http://localhost:8000/eden/pr/person/1
  }}}

  * 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 confirmation form together with a list of the specified records (if there is exactly one record identified by its ID or UID, then the record will be deleted instead of a form being returned, see POST)

  ''Example:'' '''create''' form for the pr_person table
  {{{
http://localhost:8000/eden/pr/person/create
  }}}

  * some resources support other (custom) methods, e.g.
    - '''search_simple''' returns a form for simple string search in the resource

  Example: simple '''search''' for a person by name or ID
  {{{
http://localhost:8000/eden/pr/person/search_simple
  }}}
==== Non-interactive formats ====

  * without '''method''':
    - returns all matching records in the specified format

  ''Example:'' all {{{person}}} records the user is allowed to read, in PFIF format:
  {{{
http://localhost:8000/eden/pr/person.pfif
  }}}


  * 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

  ''Example:'' import data from that URL into the {{{person}}} resource:
  {{{
http://localhost:8000/eden/pr/person.xml/create?fetchurl=http://vita.sahanafoundation.org/eden/pr/person.xml
  }}} 

  * 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

----

DeveloperGuidelines