wiki:S3/S3REST/URLFormat

Version 13 (modified by Fran Boon, 13 years ago) ( diff )

--

Table of Contents

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

S3XRC | 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> }

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.field{operator}=value

  • resource is the name of the resource or component (without prefix) or the name of the context
  • field is the name of the field to be tested
  • operator is the operator
  • value is the value or a comma-separated list of values to test against (a comma will be treated as OR)

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
__likelike, LIKE(%value%)string/text types only
__unlikenot like, NOT LIKE(%value%)string/text types only
__incontainment, contains(value)list types only
__exnegative containment, not contains(value)list types only

Field Queries

  • Testing a field in the main resource 
    /pr/person?person.first_name__like=Miriam

Component Field Queries

  • Testing a field in a component resource 
    /pr/person?address.city__like=Oslo

Context Queries

  • Testing a field in a referenced resource
  • Context must be specified like context.name={component.}field
    • name is a name for the context (as reference for subsequent queries)
    • component is the name of the component resource (without prefix)
    • field is the field name of the foreign key field 
/pr/person?context.location=address.location_id&location.lat__gt=0

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 ID

Record UID

URL Queries

DeveloperGuidelines

Note: See TracWiki for help on using the wiki.