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));
  }
}

During normal operation the API will just return the ID of the file in file fields, but by passing the include_binary_data GET parameter with a value of 1, then these ID's will be replaced by a JSON structure:

Please be aware that this can produce substantial output in some cases, and is therefore only recommended for using when querying for a specific object.

A similar JSON structure can be used when posting to the API to update files. Just add another field to the JSON structure:

If remove is passed the other fields are not necessary.

The API endpoints can be queried by passing a JSON-structure in the query GET parameter. The query can consist of either a comparison statement or logical statement.

A comparison statement always consists of three fields: type, fieldname and value.

The following comparison types exists:

Logical statements are used to combine or negate other statements. They consists of the field: type and some additional fields depending on the type.

Find all data where age is equal or greater than 18

{"type":"GreaterEqual","fieldname":"age","value":18}

Find all data where age is less than 40 and gender is male

{"type":"AND","condition1":{"type":"Lesser","fieldname":"age","value":40},"condition2":{"type":"Match","fieldname":"gender","value":"male"}}

Find all data where firstname contains the letter a

{"type":"Like","fieldname":"firstname","value":"a"}

Find all data changed since a specific time stamp

{"type":"Greater","fieldname":"change_date","value":"2021-01-15 14:45:00"}