Version 5 (modified by 14 years ago) ( diff ) | ,
---|
Table of Contents
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
in interactive formats:
- see POST
in non-interactive formats:
- attempts to create/update records in a resource with the data from the request body (must be in the specified format)
- records being matched by the UIDs specified in the data rather than those in the request
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
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?contact.value__like=gmail.com