Changes between Version 3 and Version 4 of S3/S3REST


Ignore:
Timestamp:
10/22/10 13:01:20 (11 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3REST

    v3 v4  
    1414  * In '''all other formats''', main resources and subresources are addressed separately
    1515
    16 == Basic URL Syntax ==
     16== URL Syntax ==
    1717
    18    '''Parts in { } are optional, [ ] indicate alternatives'''
     18   * see [wiki:S3XRC/RESTfulAPI/URLFormat URL Format]
    1919
    20 The basic '''URL format''' is:
     20== Standard Methods ==
    2121
    22   !http://<'''path'''>/<'''prefix'''>/<'''name'''>{/<'''arguments'''>}{?<'''query'''>}
    23 
    24   ||Item||Explanation||Example||
    25   ||'''path'''||the domain and path of the Eden server||demo.sahanafoundation.org/eden||
    26   ||'''prefix'''||the '''application prefix'''||''rms'' (=Request Management System)||
    27   ||'''name'''||the '''resource name'''||''req'' (=Requests)||
    28   ||'''arguments'''||any '''method arguments'''|| ||
    29   ||'''query'''||the resource '''query'''|| ||
    30 
    31 The data format is specified as file extension to either the '''resource name''' or any of the '''method arguments''', e.g.:
    32 
    33   !http://demo.sahanafoundation.org/rms/req '''.xml'''
    34 
    35 If multiple data format extensions are specified, the rightmost applies. Any extension can be overridden by the '''format''' parameter in the '''query''':
    36 
    37   !http://demo.sahanafoundation.org/rms/req ?'''format=json'''
    38 
    39 == Method Arguments ==
    40 
    41 The '''method argument''' list uses the following syntax:
    42 
    43   { /'''id''' }{ / [ '''method''' | '''component''' { /'''component_id'''  } { /'''method''' } ] }
    44 
    45 where:
    46 
    47   * '''id''' is a record ID in the main resource
    48   * '''component''' is the name of a subresource (e.g. ''address'' is a subresource of ''person'')
    49   * '''component_id''' is the record ID in the subresource
    50   * '''method''' is a URL method (only in GET/POST requests, e.g. "create", "read", "update")
    51 
    52 == Query Syntax ==
    53 
    54 The basic query format is: '''resource'''.'''field'''{'''operator'''}='''value'''
    55 
    56   * '''resource''' is the name of the resource or component (without prefix) or the name of the context
    57   * '''field''' is the name of the field to be tested
    58   * '''operator''' is the operator
    59   * '''value''' is the value or a comma-separated list of values to test against (a comma will be treated as OR)
    60 
    61 Supported operators:
    62 
    63   ||'''Operator'''||'''Method'''||'''Comments||
    64   ||!__eq||equal, ==||can be omitted||
    65   ||!__ne||not equal, !=|| ||
    66   ||!__lt||less than, <||numeric and date types only||
    67   ||!__le||less than or equal, <=||numeric and date types only||
    68   ||!__gt||greater than, >||numeric and date types only||
    69   ||!__ge||greater than or equal, >=||numeric and date types only||
    70   ||!__like||like, LIKE(%value%)||string/text types only||
    71   ||!__unlike||not like, NOT LIKE(%value%)||string/text types only||
    72   ||!__in||containment, contains(value)||list types only||
    73   ||!__ex||negative containment, not contains(value)||list types only||
    74 
    75 === Examples ===
    76 
    77   * Testing a field in the main resource:
    78 {{{
    79   /pr/person?person.first_name__like=Miriam
    80 }}}
    81 
    82   * Testing a field in a subresource (component):
    83 {{{
    84   /pr/person?address.city__like=Oslo
    85 }}}
    86 
    87 === Context Queries ===
    88 
    89   * Testing a field in a referenced resource
    90   * Context must be specified like:
    91 
    92   '''context.'''name'''={'''component'''.}'''field'''
    93 
    94   where:
    95 
    96   * '''name''' is a name for the context (as reference for subsequent queries)
    97   * '''component''' is the name of the component resource (without prefix)
    98   * '''field''' is the field name of the foreign key field
    99 
    100 {{{
    101    /pr/person?context.location=address.location_id&location.lat__gt=0
    102 }}}
    103 
    104 == GET Methods ==
     22=== GET ===
    10523
    10624==== Interactive Formats ====
     
    13452
    13553  * XLS and PDF format work read-only (create/update/delete being ignored)
    136 == POST Method ==
     54
     55=== POST ===
    13756
    13857==== Interactive Formats ====
     
    14867  * see PUT
    14968
    150 == PUT Method ==
     69=== PUT ===
    15170
    15271==== Interactive formats ====
     
    15877  * import data from the request body (which must be in the specified format) into the resource
    15978  * records being matched by the UIDs specified in the data, while any record IDs in the URL restrict the selection
    160 == DELETE Method ==
     79
     80=== DELETE ===
    16181
    16282  * deletes those of the addressed records which are deletable by the current user
     
    181101  ||Request Management System||rms||Requests||req||/rms/req||XML, JSON, KML, GeoRSS, RSS, XLS, PDF||
    182102
    183 == URL Examples ==
    184 
    185 ==== Interactive (HTML) Format ====
    186 
    187   * http://test.sahanafoundation.org/eden/pr/person
    188 
    189 ==== Non-interactive Formats ====
    190 
    191   * http://test.sahanafoundation.org/eden/pr/person.pdf
    192   * http://test.sahanafoundation.org/eden/pr/person.rss
    193   * http://test.sahanafoundation.org/eden/pr/person.xml
    194 
    195 ==== URL Method ====
    196 
    197   * http://test.sahanafoundation.org/eden/pr/person/create
    198 
    199 ==== Record ID ====
    200 
    201   * http://test.sahanafoundation.org/eden/pr/person/1
    202 
    203   * http://test.sahanafoundation.org/eden/pr/person/1.pfif
    204   * http://test.sahanafoundation.org/eden/pr/person/1.json
    205 
    206 ==== Record UID ====
    207 
    208   * http://test.sahanafoundation.org/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac
    209 
    210 ==== URL Queries ====
    211 
    212   * http://test.sahanafoundation.org/eden/pr/person?person.id=1,2,3
    213 
    214   * http://test.sahanafoundation.org/eden/pr/person.pfif?person.first_name__like=Dominic
    215   * http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com
    216 
    217103== XML/JSON Format ==
    218104