S3XRC | 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.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:

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
__unlike	not like, NOT LIKE(%value%)	string/text types only
__in	containment, contains(value)	list types only
__ex	negative 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

• ​http://test.sahanafoundation.org/eden/pr/person

Non-interactive Formats

• ​http://test.sahanafoundation.org/eden/pr/person.pdf
• ​http://test.sahanafoundation.org/eden/pr/person.rss
• ​http://test.sahanafoundation.org/eden/pr/person.xml

URL Method

• ​http://test.sahanafoundation.org/eden/pr/person/create

Record ID

• ​http://test.sahanafoundation.org/eden/pr/person/1

• ​http://test.sahanafoundation.org/eden/pr/person/1.pfif
• ​http://test.sahanafoundation.org/eden/pr/person/1.json

Record UID

• ​http://test.sahanafoundation.org/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac

URL Queries

• ​http://test.sahanafoundation.org/eden/pr/person?person.id=1,2,3

• ​http://test.sahanafoundation.org/eden/pr/person.pfif?person.first_name__like=Dominic
• ​http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com

---

DeveloperGuidelines