= S3 RESTful API - URL Format =
[[TOC]]

  - see also: [wiki:S3/S3REST/Methods 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 [wiki:S3XRC/RESTfulAPI/Methods 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:

  ||'''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||wildcard matching, use * as wildcard||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).

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 ====

  * http://127.0.0.1:8000/eden/pr/person

==== 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) ====

  * http://127.0.0.1:8000/eden/pr/person/create

==== Record by ID ====

  * http://127.0.0.1:8000/eden/pr/person/1

  * http://127.0.0.1:8000/eden/pr/person/1.pfif
  * http://127.0.0.1:8000/eden/pr/person/1.json

==== Record by UID ====

  * http://127.0.0.1:8000/eden/pr/person?person.uid=37988e29-4e7c-4f71-bb32-93ce1a2ba1ac

==== 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 current.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

----

DeveloperGuidelines