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

== Basic URL Syntax ==

  - ''Parts in { } are optional, [ ] indicate alternatives''

The basic URL format is: /'''prefix'''/'''name'''{ /<'''arguments'''> }{ ?<'''query'''> }

  * '''prefix''' is the resource prefix (="module" name)
  * '''name''' is the resource name (without prefix)

  * '''arguments''' is a list of: { /'''id''' }{ / [ '''method''' | '''component''' { /'''component_id''' } { /'''method''' } ] }
    * '''id''' is a record ID in the main resource
    * '''component''' is a component resource name (without prefix)
    * '''component_id''' is a record ID in the component resource
    * '''method''' is a URL method (only in GET/POST requests, e.g. "create", "update" or "delete")

  * '''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