This guide will help you connect to the Arbor REST API and make your first API request.

1. Request access for the API sandbox

  • 1. Email api@arbor-education.com with a short description of what you plan to do with the API.
  • 2. You will be emailed an API endpoint, username and API key.

2. Test your credentials

  • 1. Test that you can login to your sandbox by sending a GET request to: http://your-sandbox-endpoint/rest-v2/students
  • 2. Authenticate yourself by providing your API username and key as a HTTP username and password using HTTP Basic or Digest authentication.
  • 3. The response should contain an XML document with a list of student resources!

    <?xml version="1.0" encoding="utf-8"?>
    <response>
    <status>OK</status>
    <success>true</success>
    <code>200</code>
    <students>
        <student>
            <entityType>Student</entityType>
            <href>/rest-v2/students/1</href>
        </student>
        <student>
            <entityType>Student>/entityType>
            <href>/rest-v2/students/2</href>
        </student>
        <student>
            <entityType>Student</entityType>
            <href>/rest-v2/students/3</href>
        </student>
        <student>
            <entityType>Student</entityType>
            <href>/rest-v2/students/4</href>
        </student>
    </students>
    </response>
  • 4. To get the same info back as JSON simply add an Accept header to your request:

    Accept: application/json

    Alternatively you can also just add a get param to your URL ?format=json

  • 5. You have now connected to the Arbor API and have made your first API request!

3. Arbor API Reference

Check the Arbor API Reference to find out about resource types and their properties

  • 1. Click on the API Reference link here to browse the different types of resources you can access via the API.
  • 2. Each resource has a list of properties detailing the property name and type.
  • 3. Properties can also be other resources. These are usually returned as nested XML or JSON.
  • 4. To list all objects of a particular resource type simply change the URL to:
    https://your-sandbox-endpoint/rest-v2/resourceTypeName
    
    examples:
    https://your-sandbox-endpoint/rest-v2/guardians
    https://your-sandbox-endpoint/rest-v2/rooms
    https://your-sandbox-endpoint/rest-v2/attendance-marks
                            

4. Requesting full representations

  • 1. So far you have accessed listings of objects which only contain the URL of each object. To access the full representation of that object send a GET request to the URL provided as the href property:
    https://your-api-endpoint/rest-v2/room/7
  • 2. The response will contain the full representation of the object with any related objects nested as part of the response. Here is an example in json:
    <?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>
                            

5. Writing data to the API

  • 1. To write data to the API send POST or PUT requests containing XML or JSON representations of your own.
  • 2. Use the HTTP PUT method on the resource URL to update properties of existing objects
  • 3. Use HTTP POST on the listing URL to create new objects

6. Filtering listings

  • 1. You can perform complex queries which return subsets of objects based on some filter criteria.
  • 2. You can add filter criteria to your queries by specifying one or more property filters as GET parameters:
    https://your-sanbox-endpoint/rest-v2/students?filters.person.gender.equals=/rest-v2/genders/MALE
    (NOTE: Make sure you URL encode all filter parameters!)

7. Develop faster using the Arbor SDK!

If you are using .NET or PHP as your development platform then you can download the latest Arbor SDK here: http://developers.arbor-education.com/sdk

The SDK is a class library containing models for all resource types and gateways for seamless communication with the Arbor API without the need to worry about HTTP requests and response, XML or JSON formats etc. Here is a simple and fully functional example of how you can read data from the API using the PHP SDK:

<?php
use Arbor\Api\Gateway\RestGateway;
use Arbor\Model\Student;

Student::setDefaultGateway(
    new RestGateway(
        "https://school.org/rest-v2",
        "admin@myschool.org",
        "45f%76As&r$AS^fGG"
    )
);

$students = Student::query();
foreach($students AS $student)
{
    echo "Hello ".
         $student->getDisplayName()."\n";
}