S3 | S3 RESTful API | Methods

S3 RESTful Methods

• see also: URL Format

Standard Methods

Standard methods include:

• interactive create, read, update and delete (CRUD) including list views
• non-interactive data export/import various formats, including on-the-fly transformation

Note:

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

GET

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)

Example: read view of pr_person #1 (or an update form if the user is permitted to update this record):

http://localhost:8000/eden/pr/person/1

• 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 confirmation form together with a list of the specified records (if there is exactly one record identified by its ID or UID, then the record will be deleted instead of a form being returned, see POST)

Example: create form for the pr_person table:

http://localhost:8000/eden/pr/person/create

• some resources support other (custom) methods, e.g.
  • search_simple returns a form for simple string search in the resource

Example: simple search for a person by name or ID:

http://localhost:8000/eden/pr/person/search_simple

Non-interactive formats

• without method:
  • returns all matching records in the specified format

Example: all person records the user is allowed to read, in PFIF format:

http://localhost:8000/eden/pr/person.pfif

• 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

Example: import data from that URL into the person resource:

http://localhost:8000/eden/pr/person.xml/create?fetchurl=http://vita.sahanafoundation.org/eden/pr/person.xml

• XLS and PDF format work read-only (create/update/delete being ignored)

POST

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

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

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

---

DeveloperGuidelines