Arbor API Messages
The Arbor API is a REST-full and allows access to school data via HTTP requests. Data can be both read and written using the API.
There are two type of messages used to communicate all data via the REST API:
- 1. Requests
- 2. Responses
Requests are sent to the server and response are received from the server. Both message types can use XML or JSON to communicate information.
Requests to resources will always return a response which will either contain the requested data or an error message. All responses have the following structure:
<?xml version="1.0" encoding="utf-8"?> <response> [representation] </response>
The representation will be encapsulated in an XML tag or JSON property with the name of the resource type being returned. Here is an example response for a single object:
https://sandbox.uk.arbor.sc/rest-v2/room/7 <?xml version="1.0" encoding="utf-8"?> <response> <room> <entityType>Room</entityType> <href>/rest-v2/rooms/7</href> <site> <entityType>Site</entityType> <href>/rest-v2/sites/1</href> <siteName>Site Name</siteName> <shortName>PVC</shortName> <siteDisplayOrder/> <revisionId>153295</revisionId> <userTags/> </site> <roomName>A.1.04</roomName> <shortName/> <studentCapacity>35</studentCapacity> <isInvigilationRoom>false</isInvigilationRoom> <invigilationCapacity/> <userTags/> </room> </response>
Requests which write data to the API (PUT and POST) will contain a body and this body will contain an XML document or JSON object depending on which format you prefer to work with. The two formats are interchangeable in the sense that they both contain identical information arranged in the same hierarchy of nested properties.
Typically requests for reading data from the API will be GET requests and will not contain a body.
All API POST and PUT requests contain a single resource representation with all properties which are relevant to the change or creation operation.
<room> <entityType>Room</entityType> <href>/rest-v2/rooms/7</href> <site> <entityType>Site</entityType> <href>/rest-v2/sites/1</href> </site> <roomName>A.1.04</roomName> <studentCapacity>35</studentCapacity> </room>
There are two types of properties in resource representations:
- 1. Literal properties - strings, integers, dates, etc
- 2. References to other resources
When writing data to the API we provide references as URLs using the href property of a nested object or tag. In the above example, the property "site" is a reference to another resource.
For more info about how to make requests and format URL's please refer to the API Endpoints section.
For more information about how errors are reported and handled please see the Error handling section