Differences

This shows you the differences between two versions of the page.

--- api_class [2020/09/04 05:41] – sahl
+++ api_class [2021/02/11 13:35] (current) – API query and handling files sahl
@@ Line 47: / Line 47: @@
 ...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>