wiki:S3/S3REST/URLFormat

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

--

S3 RESTful API - URL Format

Table of Contents

  1. Basic URL Syntax
  2. Basic Query Format
  3. Field Queries
  4. Boundary Box Queries
  5. URL Examples
      1. Interactive (HTML) Format
      2. Non-interactive Formats
      3. URL Method (GET)
      4. Record by ID
      5. Record by UID
      6. URL Queries

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)

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:

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

/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).

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

/pr/person?~.first_name__like=Miriam*

This refers to the first_name field in the pr_person table.

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

URL Method (GET)

Record by ID

Record by UID

URL Queries

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.