The Api class exposes any Datarecord object in a RESTful API interface. This is extremely simple to setup:

$api_endpoint = new Api(array('CLASSES_TO_INCLUDE'));
$api_endpoint->handle();

For normal use, a user using the provided API interface would have to specify an instance ID in the URL. If you don't want that (maybe because your application only consists of a single instance), you can preselect an instance like this:

$api_endpoint = new Api(array('CLASSES_TO_INCLUDE'));
$api_endpoint->setInstance(2); // Preselects instance 2. The endpoint will then always and only work on that instance.
$api_endpoint->handle();

The endpoint extends itself from the script containing the code, and have the following path /instance_id/object_name/object_id/

So if you expose a class ExampleClass in an instance with ID 2, in a file here https://www.example.com/endpoint.php then you can get all the objects by calling this URL:

https://www.example.com/endpoint.php/2/exampleclass

PRO TIP: If you have preset an instance id for the endpoint, this shouldn't be repeated in the URL, so in that case the URL would be: https://www.example.com/endpoint.php/exampleclass

If you want to retrieve the object with ID 24, then call the URL:

https://www.example.com/endpoint.php/2/exampleclass/24

To update the object, just POST to the same URL and to create a new object POST to the general URL above. One does not have to POST a complete object. Only the fields mentioned in the POST will be updated. The other fields will be left untouched. POST data should consist of a JSON-object similar to the one received when querying the API.

To delete an object make a call to DELETE

The API makes heavy use of the following functions in Datarecord to ensure proper operation:

• canAccess()
• canCreate()
• canDelete()
• canEdit()
• validateObject()

…so be sure that those are implemented properly.

By default an endpoint requires a valid access token to use. This access token should be passed in a cookie named access_token. If this cookie isn't present, it is possible to use a GET parameter named access_token instead.

This security can be removed with the setProtection() function, making the API public and usable by anyone.

// This disables the endpoint security.
$api_endpoint->setProtection(false);

Custom functionality can be added to an api endpoint, so it can be used to do more than manipulate Datarecord objects. In order to do so, one can subclass the Api-class and override the functions customHandlerBeforeSecurity() and/or customHandlerAfterSecurity() with the difference in these functions being if they are handled before or after the security check mentioned above. If protection is disabled it doesn't make a different.

In order to make API answers, the function respondAndDie() can be used. It is passed a HTTP code and a body to respond with.

In this example we construct an object called getaccesstoken which return a valid access token if the user provides a valid user name and password.

public function customerHandlerBeforeSecurity($object_name, $object_id, $method, $get) {
  // Only react on correct object
  if ($object_name == 'getaccesstoken') {
    // Check if other parameters are correct
    if ($object_id) $this->respondAndDie (404, 'Don\'t specify an object ID on this request');
    if ($method != 'GET') $this->respondAndDie (405, 'This call only support GET');
    // Validate get input
    if (! $get['username']) $this->respondAndDie (400, 'No username specified');
    if (! $get['password']) $this->respondAndDie (400, 'No password specified');
    // Try to make a login
    $accesstoken = User::tryLogin($get['username'], $get['password']);
    // Fail if the login was invalid
    if ($accesstoken === false) $this->respondAndDie (401, 'Invalid username or password');
    // Create a response
    $result = array(
      'access_token' => $accesstoken->token_code
    );
    // Respond
    self::respondAndDie(200, json_encode($result));
  }
}