S3 RESTful API

The S3 framework provides a generic RESTful API for many of the Eden data resources.

• see also S3XRC

Important to know:

• In XML and JSON, data resources are always exported/imported in compound with all their subresources and referenced resources.
• In all other formats, main resources and subresources are addressed separately

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

Interactive Formats

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

Non-interactive Formats

• see PUT

PUT Method

Interactive formats

• see POST

Non-interactive formats

• create/update records in a resource with the data from the request body (which must be in the specified format)
• records being matched by the UIDs specified in the data, while any record IDs in the URL restrict the selection

DELETE Method

• deletes those of the addressed records which are deletable by the current user

Main Resources

Application	Prefix	Resource	Resource Name	URL	Formats
Person Registry	pr	Persons	person	/pr/person	XML, JSON, PFIF, RSS, XLS, PDF
Person Registry	pr	Groups	group	/pr/group	XML, JSON, RSS, XLS, PDF
Map	gis	Locations	location	/gis/location	XML, JSON, GeoRSS, KML, GPX, RSS, XLS, PDF
Organization Registry	org	Organisations	organisation	/org/organisation	XML, JSON, RSS, XLS, PDF
Organization Registry	org	Offices	office	/org/office	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
Organization Registry	org	Projects	project	/org_project	XML, JSON, RSS, XLS, PDF
Hospital Management System	hms	Hospitals	hospital	/hms/hospital	XML, JSON, KML, GeoRSS, RSS, XLS, PDF, HAVE
Shelter Registry	cr	Shelters	shelter	/cr/shelter	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
DVI	dvi	Dead Body Recovery Requests	recreq	/dvi/recreq	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
DVI	dvi	Dead Body Files	body	/dvi/body	XML, JSON, RSS, XLS, PDF
Incident Report System	irs	Incident Messages	incident	/irs/incident	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
Incident Report System	irs	Incident Reports	ireport	/irs/ireport	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
Incident Report System	irs	Impact Assessments	iassessment	/irs/iassessment	XML, JSON, RSS, XLS, PDF
Rapid Assessment Tool	rat	Assessments	assessment	/rat/assessment	XML, JSON, KML, GeoRSS, RSS, XLS, PDF
Request Management System	rms	Requests	req	/rms/req	XML, JSON, KML, GeoRSS, RSS, XLS, PDF

URL Examples

• [GET] ​http://test.sahanafoundation.org/eden/pr/person
• [GET|POST] ​http://test.sahanafoundation.org/eden/pr/person/create
• [GET|POST|DELETE] ​http://test.sahanafoundation.org/eden/pr/person/1
• [GET|POST|PUT|DELETE] ​http://test.sahanafoundation.org/eden/pr/person.xml
• [GET|PUT] ​http://test.sahanafoundation.org/eden/pr/person.rss
• [GET|PUT|DELETE] ​http://test.sahanafoundation.org/eden/pr/person/1.pfif
• [GET|PUT|DELETE] ​http://test.sahanafoundation.org/eden/pr/person/1.json
• [GET|DELETE] ​http://test.sahanafoundation.org/eden/pr/person.json?person.name__like=Fran
• [GET|DELETE] ​http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com

XML/JSON Format

• see S3XML