Version 47 (modified by Fran Boon, 7 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> }

Serverthe server
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 } ] }


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 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]


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

__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
__contains(full) containmentlist types only
__anyof(partial) containmentlist types only
__belongsreverse containment
__typeofhierarchical type recognition
  • 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.


Find persons whose first name starts with "Mir":


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


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


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


Bracketed OR Queries

If there is a need for a more complex query, such as one which requires a bracketed OR filter, then you can use the new $filter syntax,e.g.:

?$filter=(start_date lt "2012-01-01") and ((end_date gt "2012-10-01") or (end_date eq None))

NB Be sure to quote string literals, including dates

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



URL Examples

Interactive (HTML) Format

Non-interactive Formats

URL Method (GET)

Record by ID

Record by UID

URL Queries


Note: See TracWiki for help on using the wiki.