wiki:S3/S3REST/URLFormat

Version 43 (modified by Dominic König, 8 years ago) ( diff )

--

S3 RESTful API - URL Format

URL Format

  • Parts in { } mark optional parts, [ A | B ] indicates alternatives

Basic URL Format

The basic URL format is:

http:// server / application / prefix / name{ /<arguments> }{ ?<query> }

Example:

http://demo.eden.sahanafoundation.org/eden/org/office/4/human_resource?~.person_id$first_name__like=Nor*
PartExplanationExample
Serverthe server URLdemo.eden.sahanafoundation.org
Applicationthe web2py application nameeden
Prefixthe module prefixorg
Namethe resource nameoffice
Argumentssee arguments list format4/human_resource
Querysee query format~.person_id$first_name__like=Nor*

Arguments List Format

The arguments list consists of:

{ /id }{ / [ method | component { /component_id } { /method } ] }

Example:

4/human_resource
PartExplanationExample
IDthe master record ID4
Methodthe resource method (e.g. /create or /summary)not present in example
Componentthe component resource (projected table)human_resource
Component IDthe component record IDnot present in example

Query Format

The basic query format is:

field-selector{operator}=value(s)

Example:

~.person_id$first_name__like=Nor*
PartExplanationExample
Field Selectorthe field selector~.person_id$first_name
Operatorthe query operator__like
Value(s)the search valuesNor*
  • NONE as value is interpreted as a NULL-value (=Python None)
  • multiple values can be specified separated by commas
  • a value enclosed in double quotes " is treated as string constant - i.e. commas and NONE inside the string will not be interpreted
  • only the __like operator interprets the asterisk * as wildcard (all other operators do not!)

Field Selectors

See also: S3/FieldSelectors

The general field selector syntax is:

alias.{left-key:link-table.}{foreign-key$}[field-selector | field-name]

Example:

~.person_id$first_name
PartExplanationExample
Aliasis the alias of the component without prefix (note that components may use aliases different from their table name). ~
Left Keythe foreign key field in a backward-reference (=link table points back to master/component), can be omitted if not ambiguous
Link Tablethe table name of the backward-referencing table (incl. prefix)
Foreign Keyforeign key field in a forward-reference (=component points to a referenced table), person_id
Field Namethe target field namefirst_name
  • For the master table of of the request, the alias is the tablename without prefix or just ~
  • 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
  • "integer", "list:reference" or virtual fields are not real foreign keys and can therefore not be used for $-joins
  • Field selectors represent the path to the target field (interpreted left-to-right), starting with the master resource or a component of it
  • Queries with invalid or unresolvable field selectors are ignored (but logged on stderr if in debug mode)

Query Operators

OperatorMethodComments
__eqequal, =can be omitted
__nenot equal, =||
__ltless than, <numeric and date types only
__leless than or equal, <numeric and date types only
__gtgreater than, >numeric and date types only
__gegreater than or equal, >numeric and date types only
__likewildcard matching, use * as wildcardstring/text types only
__containscontainmentlist types only
__belongsreverse containment
  • to negate a query, append ! to the operator, e.g. resource.fieldname__like!=value
  • the __like operator works case-insensitive, whereas __contains is case-sensitive.

Examples

Find persons whose first name starts with "Mir":

/pr/person?person.first_name__like=Mir*

The tilde ~ refers to the master resource addressed by the URL, i.e. this one is equivalent to the former:

/pr/person?~.first_name__like=Mir*

Find offices with location names which start with "Osl":

/org/office?~.location_id$name__like=Osl*

Query operators can be negated by inserting a !, i.e. find offices with location names which do not start with "Osl":

/org/office?~.location_id$name__like!=Osl*

Boundary Box Queries

For resources with location references (e.g. Hospitals), you can use boundary box queries select records. The general format of the query variable is:

  • ?bbox=minLon,minLat,maxLon,maxLat

You can also specify the foreign key field name of the location reference the query relates to (e.g. in case there are multiple location references in that resource):

  • ?bbox.FKFieldName=minLon,minLat,maxLon,maxLat

Examples:

/hms/hospital?bbox=123,13.5,124,13.7
/hms/hospital?bbox.location_id=123,13.5,124,13.7

URL Examples

Interactive (HTML) Format

Non-interactive Formats

URL Method (GET)

Record by ID

Record by UID

URL Queries


DeveloperGuidelines

Note: See TracWiki for help on using the wiki.