How OrionDB handles requests

OrionDB is a generic PHP Rest interface.

This article is about what this means and what kinds of responses can you expect from OrionDB for certain actions.

Rest actions are commonly abbreviated as CRUD: Create, Refresh, Update, Delete.
This kind of actions are useful in a communication with a database.

In REST, every action has more or less the same URL, but the method of sending it to OrionDB determines the actual action.

Refresh

Refresh is the same as just getting information from the server and works with the HTTP Get action. A refresh URL can have many forms, but the basic form is:

http://example.com/resources/resource_name/options

example.com is the hostname receiving the request
resources is the starting point in the webserver where OrionDB resides
resource_name can be a table name, users for example

options can exist of a few items:
when you want to only retrieve the user having id 1, you can call

http://example.com/resources/user/1

and OrionDB will return the information of user with id 1
If you omit the options, OrionDB will return all users. This is the same as sending

http://example.com/resources/user/list

as often seen with other REST interfaces (OrionDB currently does not support /list, but I will readily accept a patch, so feel free to have a go at it yourself!).

Other options enable you to send selecting properties of that record

http://example.com/resources/user?name=John

This request should return only the users having John in the name field.

If you worry about your data not being safe: OrionDB supports session keys, so you can force a user to be logged in before being able to retrieve data.

Create

Create actions are sent to OrionDB with a HTTP POST. (read more about HTTP POST at http://developers.sun.com/mobility/midp/ttips/HTTPPost)

A HTTP Post request can have many content type definitions, but the one OrionDB expects is application/x-www-form-urlencoded
Any other format will be ignored.

The request itself needs to be posted as records=data, where data is a json encoded array of objects.
OrionDB requires you to send an array, even for a single record.

Update

Update actions are sent using a HTTP PUT action. You don’t need to define a content type for PUT, but the format of sending must be

records=data

Where data is (again) an json encoded array of objects.

Delete

Delete actions are sent using a HTTP DELETE action. You need to provide the id for a delete action, if it is omitted, the delete action is canceled.
The easiest way of sending that id is of course the method already mentioned in Refresh:

DELETE http://example.com/resources/user/1