wiki:REST_API

Context Navigation

Version 9 (modified by Dominic König, 14 years ago) ( diff )
--

S3 RESTful API

see also S3XRC

Basic URL Syntax

Parts in { } are optional, [ ] indicate alternatives

The basic URL format is:

http://<path>/<prefix>/<name>{/<arguments>}{?<query>}

Item Explanation Example
path the domain and path of the Eden server demo.sahanafoundation.org/eden
prefix the application prefix rms (=Request Management System)
name the resource name req (=Requests)
arguments any method arguments
query the resource query

The data format is specified as file extension to either the resource name or any of the method arguments, e.g.:

http://demo.sahanafoundation.org/rms/req .xml

If multiple data format extensions are specified, the rightmost applies. Any extension can be overridden by the format parameter in the query:

http://demo.sahanafoundation.org/rms/req ?format=json

Method Arguments

The method argument list uses the following syntax:

{ /id }{ / [ method | component { /component_id } { /method } ] }

where:

id is a record ID in the main resource
component is the name of a subresource (e.g. address is a subresource of person)
component_id is the record ID in the subresource
method is a URL method (only in GET/POST requests, e.g. "create", "read", "update")

Query Syntax

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

Examples

Testing a field in the main resource:

  /pr/person?person.first_name__like=Miriam

Testing a field in a subresource (component):
```
  /pr/person?address.city__like=Oslo
```

Context Queries

Testing a field in a referenced resource
Context must be specified like:

context.name={component.}field

where:

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

GET Methods

in interactive formats (e.g. HTML):

A GET without method and no record ID results in a list view of the resource
A GET without method but with a record ID results in a read view of this record. If the user is permitted to update the addressed record, an update form returned instead
you may specify a method in the method argument list, e.g. create (=create new record), read (=view this record), update (=update this record) or delete (=delete this record), all of which are returning a form
some resources support other methods, e.g. search_simple to perform a simple string search (currently supported by the pr/person and hms/hospital resources)

in non-interactive formats (e.g. XML):

method arguments work like in interactive formats, except they expect the data in the request body in the respective format
all records addressed by the URL are returned in the respective format, there is no difference between (single-record-)"read" and (multi-record-)"list" view
XLS and PDF format work read-only (create/update/delete being ignored)

POST Method

in interactive formats:

performs the respective method (if specified in the request)
expects the formdata as multi-part request body

in non-interactive formats:

see PUT

PUT Method