RESTful API
The rXg exposes a RESTful API to support third-party integration. Access to the rXg via the RESTful API is controlled by the API key mechanism. Use theAdmins page to setup API key access. It is good security practice to ensure that separate accounts (and hence, unique API keys ) are used for each mechanism that will access the rXg via the RESTful API. Furthermore, each account and associated API key should be limited to the absolute minimum access rights needed to accomplish the desired tasks.
The base URL for RESTful API key access follows the form:
https://DNS.record.for.rXg/admin/scaffolds/
The use of HTTPS is required. Thus it is necessary to ensure that a proper DNS record and SSL certificate is configured on the target rXg. Furthermore, it is important that the caller be able to correctly validate the installed SSL certificate.
The desired model must be appended to the base URL. The model describes the underlying database table that will be accessed. For example:
https://DNS.record.for.rXg/admin/scaffolds/accounts/
The models that are available for access via the RESTful API are described in the rXg API documentation.
The desired action must also be appended to the URL. For example:
https://DNS.record.for.rXg/admin/scaffolds/accounts/create/
The set of possible actions are create, show (or list), update and destroy. These correspond to the standard database CRUD semantics. The appropriate HTTP verb must be used in conjunction with the selected action.
| create | HTTP POST | | show | HTTP GET | | list | HTTP GET | | update | HTTP PUT | | destroy | HTTP DELETE |
There is an optional format parameter that may be appended to the URL. For example:
https://DNS.record.for.rXg/admin/scaffolds/accounts/index.html/
https://DNS.record.for.rXg/admin/scaffolds/accounts/index.xml/
https://DNS.record.for.rXg/admin/scaffolds/accounts/index.json/
Specifying the optional parameter changes the format for both the input and output presentation. For example, sending a HTTP GET to:
https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.html
Results in the following output:
`
- Login
- cpatterson746
- First name
- Colin
- Last name
- Patterson
- [email protected] [unknown]
...
`
Use the XML format specification by sending sending a HTTP GET to:
https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.xml
Results in the following output:
<account>
<bill-at type="datetime" nil="true"/>
<created-at type="datetime">2012-05-10T11:41:40-04:00</created-at>
<email>[email protected]</email>
<first-name>Colin</first-name>
<id type="integer">3</id>
<last-name>Patterson</last-name>
<logged-in-at type="datetime">2012-05-08T01:24:51-04:00</logged-in-at>
<login>cpatterson746</login>
...
For JSON, send a HTTP GET such as:
https://DNS.record.for.rXg/admin/scaffolds/accounts/index/3.json
Results in the following output:
{"created_at":"2012-05-10T11:41:40-04:00",
"email":"[email protected]","first_name":"Colin","id":3,
"last_name":"Patterson","logged_in_at":"2012-05-08T01:24:51-04:00",
"login":"cpatterson746",
...
}
It is also necessary to set the Content-Type HTTP header to the appropriate value (e.g., application/xml for XML) when using the optional format parameters.
