Version 31 (modified by Dominic König, 11 years ago) ( diff )


S3 | S3 RESTful API | URL Format

S3 RESTful API - URL Format

Basic URL Syntax

  • Parts in { } mark optional parts, [ A | B ] indicates alternatives

The basic URL format is:

http:// server / path / prefix / name{ /<arguments> }{ ?<query> }

  • server ( 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)

The tilde ~ as resource name is interpreted as "this resource" (=the master resource addressed by the URL).

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:

__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
__likelike, LIKE(%value%)string/text types only
__containscontainmentlist types only
__belongsreverse 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:


Master resources use their table name without controller prefix as alias, whereas components can have a context-dependent alias (which must be used here).

The tilde ~ refers to the master resource addressed by the URL:


This refers to the first_name field in the pr_person table.



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.


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



URL Examples

Interactive (HTML) Format

Non-interactive Formats

URL Method (GET)

Record by ID

Record by UID

URL Queries

(can use s3xrc.xml.ISOFORMAT as format string)


Note: See TracWiki for help on using the wiki.