S3 RESTful API - URL Format

• see also: Standard Methods

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*

Part	Explanation	Example
Server	the server URL	demo.eden.sahanafoundation.org
Application	the web2py application name	eden
Prefix	the module prefix	org
Name	the resource name	office
Arguments	see arguments list format	4/human_resource
Query	see 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

Part	Explanation	Example
ID	the master record ID	4
Method	the resource method (e.g. /create or /summary)	not present in example
Component	the component resource (projected table)	human_resource
Component ID	the component record ID	not present in example

Query Format

The basic query format is:

field-selector{operator}=value(s)

Example:

~.person_id$first_name__like=Nor*

Part	Explanation	Example
Field Selector	the field selector	~.person_id$first_name
Operator	the query operator	__like
Value(s)	the search values	Nor*

• 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

Part	Explanation	Example
Alias	is the alias of the component without prefix (note that components may use aliases different from their table name).	~
Left Key	the foreign key field in a backward-reference (=link table points back to master/component), can be omitted if not ambiguous
Link Table	the table name of the backward-referencing table (incl. prefix)
Foreign Key	foreign key field in a forward-reference (=component points to a referenced table),	person_id
Field Name	the target field name	first_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

Operator	Method	Comments
__eq	equal, =	can be omitted
__ne	not equal, =||
__lt	less than, <	numeric and date types only
__le	less than or equal, <	numeric and date types only
__gt	greater than, >	numeric and date types only
__ge	greater than or equal, >	numeric and date types only
__like	wildcard matching, use * as wildcard	string/text types only
__contains	(full) containment	list types only
__anyof	(partial) containment	list types only
__belongs	reverse containment
__typeof	hierarchical 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.

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

• ​http://127.0.0.1:8000/eden/pr/person

Non-interactive Formats

• ​http://127.0.0.1:8000/eden/pr/person.pdf
• ​http://127.0.0.1:8000/eden/pr/person.rss
• ​http://127.0.0.1:8000/eden/pr/person.xml

URL Method (GET)

• ​http://127.0.0.1:8000/eden/pr/person/create

Record by ID

• ​http://127.0.0.1:8000/eden/pr/person/1

• ​http://127.0.0.1:8000/eden/pr/person/1.pfif
• ​http://127.0.0.1:8000/eden/pr/person/1.json

Record by UID

• ​http://127.0.0.1:8000/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac

URL Queries

• ​http://127.0.0.1:8000/eden/pr/person?person.id=1,2,3
• ​http://127.0.0.1:8000/eden/org/office?office.type=None,1,2,3,4&office.obsolete=False
• ​http://127.0.0.1:8000/eden/org/office?office.modified_on__gt=YYYYMMDDTHH:mm:ss
  • (can use current.xml.ISOFORMAT as format string)

• ​http://127.0.0.1:8000/eden/pr/person.pfif?person.first_name__like=Dominic*
• ​http://127.0.0.1:8000/eden/pr/person.xml?contact.value__like=*gmail.com

---

DeveloperGuidelines