Version 27 (modified by 12 years ago) ( diff ) | ,
---|
Table of Contents
S3 | S3 RESTful API | URL Format
S3 RESTful API - URL Format
- see also: Standard Methods
Basic URL Syntax
- Parts in { } mark optional parts, [ A | B ] indicates alternatives
The basic URL format is:
http:// server / path / prefix / name{ /<arguments> }{ ?<query> }
Example:
http://vita.sahanafoundation.org/eden/hms/hospital/1/bed_capacity/create
- server (
vita.sahanafoundation.org
) is the server, path (/eden
) the path to the application
- prefix (
/hms
) is the application prefix (="module" name) of the resource - name (
/hospital
) is the resource name (without prefix)
The arguments list consists of:
{ /id }{ / [ method | component { /component_id } { /method } ] }
- id (
/1
) is a record ID in the main resource - component (
/bed_capacity
) is a component resource name (without prefix) - component_id is a record ID in the component resource
- method (
/create
) is a URL method
For the query syntax, see below
Basic Query Format
The basic query format is: resource.{foreign key$}field{operator}=value(s)
- resource is the name of the resource or component (without prefix)
- foreign key is the name of the foreign key field
- field is the name of the field in the target table
- operator is the operator
- value(s) is the value or a comma-separated list of values to test against (a comma will be treated as OR)
None
as value can be specified as NONE
in the URL (all-uppercase).
Values with commas are always treated as a list of values. A value enclosed in double quotes "
is treated as string constant - i.e. commas and NONE
inside the string will not be interpreted in this case.
It is possible to chain $
selectors like in resource.foreign_key$foreign_key$fieldname=value
to select fields in tables which are two or more forward references away.
Supported 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 like, LIKE(%value%) string/text types only __contains containment list types only __belongs reverse containment
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.
Field Queries
Field names in URL queries must be prefixed by the resource alias, followed by a "." dot, like:
Master resource:
/pr/person?person.first_name__like=Miriam
Master resources use their table name without controller prefix as alias, whereas components can have a context-dependent alias (which must be used here).
Component:
/pr/person?address.city__like=Oslo
Note that any component of the master resource can be queried, even if it is not addressed by the URL.
To query a field in a referenced record, append the foreign key field name followed by a "$" sign to the resource name prefix.
/pr/person?person.location_id$lat__lt=55.0
This requires that the respective foreign key field is defined as "reference" type ("integer", "list:reference" or virtual fields are not real foreign keys and can therefore not be used for $-joins).
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
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 s3xrc.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