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*

Find all people *without* a specific [set of] qualification(s):

This isn't supported out of the box, as it cannot be done with WHERE clause(s). However it is easy to do it with a little custom code:

def customise_pr_person_resource(r, tablename):
    # Filtered Component to allow an exclusive filter
    s3db = current.s3db
    ctable = s3db.hrm_certificate
    query = (ctable.name.like("Fire%")) & \
            (ctable.deleted == False)
    rows = current.db(query).select(stable.id)
    fire_cert_ids = [row.id for row in rows]
    s3db.add_components("pr_person",
                        hrm_certification = {"name": "missing_qualification",
                                             "joinby": "person_id",
                                             "filterby": {"certificate_id": fire_cert_ids},
                                             },
                        )
settings.customise_pr_person_resource = customise_pr_person_resource

Then you can do:

/pr/person?missing_qualification.id=None

(This can be then further refined using standard UI Filter Widgets)

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

Examples:

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

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

Bypassing FilterForm Default Filters

'Hard' Filters (added by the developers in the controller) can never be bypassed by URL filters.

However 'Soft' Filters which are where a FilterForm is configured to have Default Filters for convenience of interactive users rather than security, or other meaning, can be.

To instruct a FilterForm to NOT implement the Default Filters, add ?default_filters=0 to the URL.

• Note that these aren't required for non-interactive requests, such as XML, GeoJSON, XLS, etc

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