[[TOC]]
[wiki:S3XRC] | [wiki:S3XRC/RESTfulAPI S3 RESTful API] | URL Format
= S3 RESTful API - URL Format =

  - see also: [wiki:S3XRC/RESTfulAPI/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'''.'''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
}}}

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