Version 27 (modified by 14 years ago) ( diff ) | ,
---|
Table of Contents
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
Interactive Formats
- without method:
- if no record ID/UID in the URL: list view of the resource
- with a record ID/UID in the URL: read view of the specified record (if the user is permitted to update the record, an update form returned instead)
- with method in the URL:
- method create returns a create-form
- method read returns a view of the specified record (other than with blank method, no update form is returned in this case)
- method update returns an update form for the specified record
- method delete returns a delete form for the specified records
- some resources support other (custom) methods, e.g.
- search_simple returns a form for simple string search in the resource
Non-interactive formats
- without method:
- returns a list of all matching records in the specified format
- with method in the URL:
- method create or update imports data into the resource from the specified data source:
- ?filename= variable to specify a local file (on the server)
- ?fetchurl= variable to specify a source URL
- with format extension .url data are imported directly from the URL
- if none of the above is specified, data are imported from the request body
- method read returns a the specified records in the requested format
- method delete deletes the specified records
- method create or update imports data into the resource from the specified data source:
- 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)
- method create creates a new record
- method update updates the specified record
- method delete deletes the specified record
- expects the form data as multi-part request body
Non-interactive Formats
- see PUT
PUT Method
Interactive formats
- see POST
Non-interactive formats
- import data from the request body (which must be in the specified format) into the resource
- 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
Interactive (HTML) Format
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
Record ID
- http://test.sahanafoundation.org/eden/pr/person/1.pfif
- http://test.sahanafoundation.org/eden/pr/person/1.json
Record UID
URL Queries
- http://test.sahanafoundation.org/eden/pr/person.json?person.name__like=Fran,Praneeth
- http://test.sahanafoundation.org/eden/pr/person.xml?pe_contact.value__like=gmail.com
XML/JSON Format
- see S3XML