Version 53 (modified by 5 years ago) ( diff ) | ,
---|
S3 RESTful API - URL Format
Table of Contents
- 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 (=PythonNone
)- multiple values can be specified separated by commas
- a value enclosed in double quotes
"
is treated as string constant - i.e. commas andNONE
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
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)
Record by ID
Record by UID
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