Changes between Version 28 and Version 29 of S3/S3REST/Methods


Ignore:
Timestamp:
01/03/14 11:04:01 (12 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • S3/S3REST/Methods

    v28 v29  
    22[[TOC]]
    33
     4This page describes the standard (built-in) CRUD methods of the Eden RESTful API.
     5
    46  - see also: [wiki:S3/S3REST/URLFormat URL Format]
    57
    6 == Standard Methods ==
     8  '''Note:''' CRUD methods may (and in most setups do) require '''access authorization'''.
    79
    8 Standard methods include:
     10  '''Note:''' the RESTful API is '''extensible''', therefore other methods may also be supported (e.g. /report, /summary, /profile). These methods are described with the documentation of the respective method handlers.
    911
    10   - interactive create, read, update and delete (CRUD) including list views
    11   - non-interactive data export/import various formats, including [wiki:S3XRC/S3XML/Transformation on-the-fly transformation]
     12  '''Note:''' Developers '''should not alter or override''' standard methods for any resources (although this is not strictly forbidden).
    1213
    13 Note:
    14   - in XML and JSON, data resources are always exported/imported in compound with all their subresources and referenced resources.
    15   - in other formats, main resources and subresources are to be addressed separately
    16 === GET ===
     14== Interactive Methods ==
    1715
    18 ==== Interactive Formats ====
     16Interactive formats include: html, iframe
    1917
    20   * without method:
    21     - if no record ID/UID in the URL: '''list''' view of the resource
    22     - 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)
     18||='''Method'''=||='''GET'''=||='''POST'''=||='''PUT'''=||='''DELETE'''=||
     19||'''resource'''||return a view of all available records in the resource (Standard: data table)||submission of a form to create a new record||see POST||-||
     20||'''resource/<ID>'''||return a view of a single record (update form if permitted, otherwise read-only)||submission of a form to update a record||see POST||delete the specified record||
     21||'''resource/create'''||return a form to create a new record||submission of a form to create a new record||see POST||-||
     22||'''resource/<ID>/read'''||return a view of a single record (read-only)||-||-||-||
     23||'''resource/<ID>/update'''||return a form to update the specified record||submission of a form to update a record||see POST||-||
     24||'''resource/delete'''||get a form to confirm the deletion of records||delete all records||-||see POST||
     25||'''resource/<ID>/delete'''||delete the specified record||see GET||-||see GET||
    2326
    24   ''Example:'' '''read''' view of pr_person !#1 (or an '''update''' form if the user is permitted to update this record):
    25   {{{
    26 http://localhost:8000/eden/pr/person/1
    27   }}}
     27== Transformable Formats ==
    2828
    29   * with '''method''' in the URL:
    30     - method '''create''' returns a create-form
    31     - method '''read''' returns a view of the specified record (other than with blank method, no update form is returned in this case)
    32     - method '''update''' returns an update form for the specified record
    33     - 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)
     29Transformable formats include: xml, json, s3csv
    3430
    35   ''Example:'' '''create''' form for the pr_person table:
    36   {{{
    37 http://localhost:8000/eden/pr/person/create
    38   }}}
     31||='''Method'''=||='''GET'''=||='''POST'''=||='''PUT'''=||='''DELETE'''=||
     32||'''resource'''||export all (accessible) records in the specified resource||see PUT||import records from the request body||-||
     33||'''resource/<ID>'''||export the specified record||see PUT||import (update) the specified record from the request body||-||
     34||'''resource/create'''||return a resource structure description of the specified resource||see PUT||import records from the request body||-||
     35||'''resource/create?filename=xyz.xml'''||import new records from the specified file||see PUT||import records from the request body||-||
     36||'''resource/create?fetchurl=!http://site/xyz.xml'''||import new records from the specified URL||see PUT||import records from the request body||-||
     37||'''resource/update'''||return a resource structure description of the specified resource||see PUT||import records from the request body||-||
     38||'''resource/update?filename=xyz.xml'''||import new records from the specified file||see PUT||import records from the request body||-||
     39||'''resource/update?fetchurl=!http://site/xyz.xml'''||import new records from the specified URL||see PUT||import records from the request body||-||
     40||'''resource/<ID>/update?filename=xyz.xml'''||import a record update from the specified file||see PUT||import a record update from the request body||-||
     41||'''resource/<ID>/update?fetchurl=!http://site/xyz.xml'''||import a record update from the specified URL||see PUT||import a record update from the request body||-||
     42||'''resource/read'''||export all (accessible) records in the specified resource||see PUT||import records from the request body||-||
     43||'''resource/<ID>/read'''||export the specified record||see PUT||import a record update from the request body||-||
     44||'''resource/delete'''||-||-||-||Delete all accessible records in the resource||
     45||'''resource/<ID>/delete'''||-||-||-||Delete the specified record||
    3946
    40   * some resources support other (custom) methods, e.g.
    41     - '''search_simple''' returns a form for simple string search in the resource
    42 
    43   ''Example:'' simple '''search''' for a person by name or ID:
    44   {{{
    45 http://localhost:8000/eden/pr/person/search_simple
    46   }}}
    47 ==== Non-interactive formats ====
    48 
    49   * without '''method''':
    50     - returns all matching records in the specified format
    51 
    52   ''Example:'' all {{{person}}} records the user is allowed to read, in PFIF format:
    53   {{{
    54 http://localhost:8000/eden/pr/person.pfif
    55   }}}
    56 
    57 
    58   * with '''method''' in the URL:
    59     - method '''create''' or '''update''' imports data into the resource from the specified data source:
    60       * ''?filename='' variable to specify a local file (on the server)
    61       * ''?fetchurl='' variable to specify a source URL
    62       * with format extension ''.url'' data are imported directly from the URL
    63       * if none of the above is specified, data are imported from the request body
    64     - method '''read''' returns a the specified records in the requested format
    65     - method '''delete''' deletes the specified records
    66 
    67   ''Example:'' import data from that URL into the {{{person}}} resource:
    68   {{{
    69 http://localhost:8000/eden/pr/person.xml/create?fetchurl=http://vita.sahanafoundation.org/eden/pr/person.xml
    70   }}}
    71 
    72   * XLS and PDF format work read-only (create/update/delete being ignored)
    73 
    74 === POST ===
    75 
    76 ==== Interactive Formats ====
    77 
    78   * performs the respective '''method''' (if specified in the request)
    79     - method '''create''' creates a new record
    80     - method '''update''' updates the specified record
    81     - method '''delete''' deletes the specified record
    82   * expects the form data as multi-part request body
    83 
    84 ==== Non-interactive Formats ====
    85 
    86   * see PUT
    87 
    88 === PUT ===
    89 
    90 ==== Interactive formats ====
    91 
    92   * see POST
    93 
    94 ==== Non-interactive formats ====
    95 
    96   * import data from the request body (which must be in the specified format) into the resource
    97   * records being matched by the UIDs specified in the data, while any record IDs in the URL restrict the selection
    98 
    99 === DELETE ===
    100 
    101   * deletes those of the addressed records which are deletable by the current user
     47  '''Note:''' in XML and JSON, data resources are always exported/imported in compound with all their subresources and referenced resources.
    10248
    10349----