wiki:S3/S3REST/URLFormat

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
__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.

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

Non-interactive Formats

URL Method (GET)

Record by ID

Record by UID

URL Queries


DeveloperGuidelines

Last modified 16 months ago Last modified on 04/09/20 13:18:13
Note: See TracWiki for help on using the wiki.