Changes between Version 37 and Version 38 of S3/S3REST/URLFormat


Ignore:
Timestamp:
12/23/13 10:53:54 (11 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • S3/S3REST/URLFormat

    v37 v38  
    44  - see also: [wiki:S3/S3REST/Methods Standard Methods]
    55
    6 == Basic URL Syntax ==
     6== URL Format ==
    77
    88  - ''Parts in { } mark optional parts, [ A | B ] indicates alternatives''
    99
     10=== Basic URL Format ===
     11
    1012The basic URL format is:
    1113
    12   !http:// '''server''' / '''path''' / '''prefix''' / '''name'''{ /<'''arguments'''> }{ ?<'''query'''> }
     14  !http:// '''server''' / '''application''' / '''prefix''' / '''name'''{ /<'''arguments'''> }{ ?<'''query'''> }
    1315
    14   ''Example:''
    15   {{{
    16 http://vita.sahanafoundation.org/eden/hms/hospital/1/bed_capacity/create
    17   }}}
     16''Example:''
     17{{{
     18http://demo.eden.sahanafoundation.org/eden/org/office/4/human_resource?~.person_id$first_name__like=Nor*
     19}}}
    1820
    19   * '''server''' ('''{{{vita.sahanafoundation.org}}}''') is the server, '''path''' ('''{{{/eden}}}''') the path to the application
     21||=''Part''=||=''Explanation''=||=''Example''=||
     22||'''Server'''||the server URL||{{{demo.eden.sahanafoundation.org}}}||
     23||'''Application'''||the web2py application name||{{{eden}}}||
     24||'''Prefix'''||the module prefix||{{{org}}}||
     25||'''Name'''||the resource name||{{{office}}}||
     26||'''Arguments'''||''see arguments list format''||{{{4/human_resource}}}||
     27||'''Query'''||''see query format''||{{{~.person_id$first_name__like=Nor*}}}||
    2028
    21   * '''prefix''' ('''{{{/hms}}}''') is the application prefix (="module" name) of the resource
    22   * '''name''' ('''{{{/hospital}}}''') is the resource name (without prefix)
     29=== Arguments List Format ===
    2330
    24 The '''arguments''' list consists of:
     31The arguments list consists of:
    2532
    2633  { /'''id''' }{ / [ '''method''' | '''component''' { /'''component_id''' } { /'''method''' } ] }
    2734
    28   * '''id''' ('''{{{/1}}}''') is a record ID in the main resource
    29   * '''component''' ('''{{{/bed_capacity}}}''') is a component resource name (without prefix)
    30   * '''component_id''' is a record ID in the component resource
    31   * '''method''' ('''{{{/create}}}''') is a URL [wiki:S3XRC/RESTfulAPI/Methods method]
     35''Example:''
     36{{{
     374/human_resource
     38}}}
    3239
    33 For the '''query''' syntax, see below
    34 == Basic Query Format ==
     40||=''Part''=||=''Explanation''=||=''Example''=||
     41||'''ID'''||the master record ID||{{{4}}}||
     42||'''Method'''||the resource method (e.g. /create or /summary)||''not present in example''||
     43||'''Component'''||the component resource (projected table)||{{{human_resource}}}||
     44||'''Component ID'''||the component record ID||''not present in example''||
    3545
    36 The basic query format is: '''resource'''.{'''foreign key'''$}'''field'''{'''operator'''}='''value(s)'''
     46=== Query Format ===
    3747
    38   * '''resource''' is the name of the resource or component (without prefix)
    39   * '''foreign key''' is the name of the foreign key field
    40   * '''field''' is the name of the field in the target table
    41   * '''operator''' is the operator
    42   * '''value(s)''' is the value or a comma-separated list of values to test against (a comma will be treated as OR)
     48The basic query format is:
    4349
    44 The tilde {{{~}}} as resource name is interpreted as "this resource" (=the master resource addressed by the URL).
     50  '''field-selector'''{'''operator'''}='''value(s)'''
    4551
    46 {{{None}}} as value can be specified as {{{NONE}}} in the URL (all-uppercase).
     52''Example:''
     53{{{
     54~.person_id$first_name__like=Nor*
     55}}}
    4756
    48 Values with commas are always treated as a list of values. A value enclosed in double quotes {{{"}}} is treated as string constant - i.e. commas and {{{NONE}}} inside the string will not be interpreted in this case.
     57||=''Part''=||=''Explanation''=||=''Example''=||
     58||'''Field Selector'''||the field selector||{{{~.person_id$first_name}}}||
     59||'''Operator'''||the query operator||{{{__like}}}||
     60||'''Value(s)'''||the search values||{{{Nor*}}}||
    4961
    50 It is possible to chain {{{$}}} selectors like in {{{resource.foreign_key$foreign_key$fieldname=value}}} to select fields in tables which are two or more forward references away.
     62  * {{{NONE}}} as value is interpreted as a NULL-value (=Python {{{None}}})
     63  * multiple values can be specified separated by commas
     64  * a value enclosed in double quotes {{{"}}} is treated as string constant - i.e. commas and {{{NONE}}} inside the string will not be interpreted
     65  * only the {{{__like}}} operator interprets the asterisk {{{*}}} as wildcard (all other operators do not!)
    5166
    52 Supported operators:
     67==== Field Selectors ====
     68
     69The general field selector syntax is:
     70
     71   '''alias'''.{'''left-key''':'''link-table'''.}{'''foreign-key'''$}['''field-selector''' | '''field-name''']
     72
     73''Example:''
     74{{{
     75~.person_id$first_name
     76}}}
     77
     78||=''Part''=||=''Explanation''=||=''Example''=||
     79||'''Alias'''||is the alias of the component without prefix (note that components may use aliases different from their table name). ||{{{~}}}||
     80||'''Left Key'''||the foreign key field in a backward-reference (=link table points back to master/component), can be omitted if not ambiguous|| ||
     81||'''Link Table||the table name of the backward-referencing table (incl. prefix)|| ||
     82||'''Foreign Key'''||foreign key field in a forward-reference (=component points to a referenced table), ||{{{person_id}}}||
     83||'''Field Name'''||the target field name||{{{first_name}}}||
     84
     85  * For the master table of of the request, the '''alias''' is the tablename without prefix or just {{{~}}}
     86  * Foreign key references can be chained (separated by $) if the referenced table is more than one reference level away, like in {{{resource.foreign_key$foreign_key$fieldname=value}}}
     87  * "integer", "list:reference" or virtual fields are not real foreign keys and can therefore not be used for $-joins
     88  * Field selectors represent the ''path'' to the target field (interpreted left-to-right), starting with the master resource or a component of it
     89  * Queries with invalid or unresolvable field selectors are ignored (but logged on stderr if in debug mode)
     90
     91==== Query Operators ====
    5392
    5493  ||'''Operator'''||'''Method'''||'''Comments||
    … …  
    63102  ||!__belongs||reverse containment||||
    64103
    65 To negate a query, append {{{!}}} to the operator, e.g. {{{resource.fieldname__like!=value}}}.
     104  * to negate a query, append {{{!}}} to the operator, e.g. {{{resource.fieldname__like!=value}}}
     105  * the {{{__like}}} operator works case-insensitive, whereas {{{__contains}}} is case-sensitive.
    66106
    67 The {{{like}}} operator works case-insensitive, whereas {{{contains}}} is case-sensitive.
    68 == Field Queries ==
     107==== Examples ====
    69108
    70 Field names in URL queries must be prefixed by the resource alias, followed by a "." dot, like:
    71 
    72 Master resource:
     109Filtering persons by their first name:
    73110
    74111{{{
    … …  
    76113}}}
    77114
    78 Master resources use their table name without controller prefix as alias, whereas components can have a context-dependent alias (which must be used here).
    79 
    80 The tilde {{{~}}} refers to the master resource addressed by the URL:
     115The tilde {{{~}}} refers to the master resource addressed by the URL, i.e. {{{pr_person}}} in this case:
    81116
    82117{{{
    … …  
    84119}}}
    85120
    86 This refers to the {{{first_name}}} field in the {{{pr_person}}} table.
    87 
    88 Component:
     121Filtering offices by the name of their location:
    89122
    90123{{{
    91 /pr/person?address.city__like=*Oslo*
     124/org/office?~.location_id$name__like=Osl*
    92125}}}
    93126
    94 Note that any component of the master resource can be queried, even if it is not addressed by the URL.
    95 
    96 To query a field in a referenced record, append the foreign key field name followed by a "$" sign to the resource name prefix.
    97 
    98 {{{
    99 /pr/person?person.location_id$lat__lt=55.0
    100 }}}
    101 
    102 This requires that the respective foreign key field is defined as "reference" type ("integer", "list:reference" or virtual fields are not real foreign keys and can therefore not be used for $-joins).
    103127
    104128== Boundary Box Queries ==