====== Api Class ======

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

<code php>
$api_endpoint = new Api(array('CLASSES_TO_INCLUDE'));
$api_endpoint->handle();
</code>

==== Preselecting an instance ====

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:

<code php>
$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();
</code>



===== Using the provided endpoint =====

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.

===== Endpoint security =====

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.

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

===== Custom functionality =====

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.

<code php>
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));
  }
}
</code>


===== Handling file fields in the API =====
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:

^filename|The filename of the file|
^mimetype|The mime type of the file|
^binary|The file binary data as base64|

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:

^action|add to add a file and remove to remove the file currently in place.|

If //remove// is passed the other fields are not necessary. 

===== Querying the API =====
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.

==== Comparison statement ====

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

The following comparison types exists:

^Type^Meaning^
|Greater|Return everything where //fieldname// is greater than //value//.|
|GreaterEqual|Return everything where //fieldname// is greater than or equal to //value//.|
|Lesser|Return everything where //fieldname// is lesser than //value//.|
|LesserEqual|Return everything where //fieldname// is lesser than or equal to //value//.|
|Like|Return everything where //value// is contained in //fieldname//.|
|Match|Return everything where //fieldname// equals //value//.|
|OneOf|Return everything where //fieldname// is one of //value// and //value// is an array.|

==== Logical statement ====

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

^type^additional fields^Meaning^
|AND|//condition1//, //condition2//|Return everything which satisfies both //condition1// and //condition2// (where each is a statement)|
|OR|//condition1//, //condition2//|Return everything which satisfies either //condition1// or //condition2// (where each is a statement)|
|NOT|//condition//|Return everything which doesn't satisfies //condition// (where //condition// is a statement)|

==== Examples ====
Find all data where age is equal or greater than 18
<code javascript>
{"type":"GreaterEqual","fieldname":"age","value":18}
</code>

Find all data where age is less than 40 and gender is male
<code javascript>
{"type":"AND","condition1":{"type":"Lesser","fieldname":"age","value":40},"condition2":{"type":"Match","fieldname":"gender","value":"male"}}
</code>

Find all data where firstname contains the letter a
<code javascript>
{"type":"Like","fieldname":"firstname","value":"a"}
</code>

Find all data changed since a specific time stamp
<code javascript>
{"type":"Greater","fieldname":"change_date","value":"2021-01-15 14:45:00"}
</code>