Introduction

Plugins This functionality serves to extend the Ordering API functionalities to anything you want without any restriction. Ordering allows these plugins to be developed in any programming language taking into account that it works through HTTP requests. The plugins can be uploaded to any server to be hosted.

With the plugins you can do almost anything you want, your imagination is the limit. This functionality is so powerful that for example, you can add endpoints using the URL of the plugin. Suppose that you want to add a new Endpoint for a "new thing", it is not necessary to contact the developers of the "Ordering API" to make the modification, instead, you can add this new functionality taking advantage of the plugins. for example:

This is how we have a plugin in the database:

{
  id: 1,
  name: "MyPlugin",
  root: "http://MyhostPlugin.ordering.co",
  author: "Some Developer(s)",
  ... 
}

As you can see, all the plugins added have the root parameter which is where the plugins are obtained to be used, and from this, the endpoints can be extended by using this URL like this:

https://MyhostPlugin.yourdomain.com/CreateNewThing or https://MyhostPlugin.yourdomain.com/GetNewThing

With this, you can understand the power and scope of the plugins, and it is emphasized that because it can be developed in any programming language the limit is only the skills of the developer.

The only requirement of the plugins is that the file "config.json" must exist in the root and must be allowed to being accessible by HTTP requests. That file must have at least the name attribute.

See the example below:

{
        "name": "Example Ordering X", //this attribute is the only real requirement.
        "description": "Description for Example Ordering",
        "author": "Ordering Inc",
        "url": "https://ordering.co",
        "version": "0.0.1",
        "hooks": {
            "actions": {
                "users_register": "/action_users_register.php",
                "users_update": [
                    "/action_users_update.php",
                    {
                        "url": "/action_users_register.php",
                        "delay": "delivery_time"
                    }
                ]
            },
            "filters": {
                "users_register": "/filter_users_register.php",
                "users_update": "/filter_users_update.php",
                "users_get": [
                    "/filter_users_get.php"
                ]
            }
        }
    }

📘
How delay works.

Now with these plugins receive also objects with the attribute "delay" & "url", to add a new delay to a specific plugin that you require.

This only works for delay parameter, integer between 0 and 60 seconds, receives delivery_time& pickup_time.

Funtions

The plugins have two essential functions of execution action and filter:

Action: Execute extra actions of the existing ones in the API, this will be executed when the hook is called in the system. This function does NOT affect the output of the API., Ex. add extra data to a business.
Filter: This function can modify request's responses, is executed when the hook is called in the system. This function does affect the output of the API and must return the transformed data. the filters can delay the response time of the requests, this also affects the time in which an action is executed if it is after a filter.

All the functions in the plugins are executed in the order in which they were added in the file "config.json".

Functioning

The plugins are activated depending on the resource used in the API since some of them have events to extend their functionalities. These events are activated as long as the resource is used and the hook is enabled in the config.json. All the requests that are made to the plugins, Ordering API made it via POST and send in the response a JSON object with three attributes.

🚧
If it is a filter, the plugin must send all the information in a JSON to avoid causing an error.

data: This contains all the data of the original request response and can be an object or an array depending on the type of request. Ex. If the request is to bring the businesses list, the attribute will be an array of businesses.
params: This attribute is an array that contains all the parameters that were used for the HTTP request, such as limit, offset or params.
query: This attribute contains all the path params used in the original request in an array, this means for example that it will always bring with it version, language and project, adding the additional parameters that have been used in the request.

In order to be understood more clearly, we will make an example below:

Suppose that in the plugin we have listed the users_get hook and we use the Find User resource.

GET https://apiv4.ordering.co/v400/en/demo/users/1?params=id,name,lastname,phone,address

This will return an object with its attributes equal to the following, the data attribute will bring a user object and the other parameters of the request:

{
  data:{
    "id": 1,
    "name": "Demo",
    "lastname": "Admin",
    "phone": "2332223",
    "address": "500 5th Ave, New York, NY 10110, USA"
  },
  params: {
    params: 'id,name,lastname,phone,address'
  },
  query: {
    version: 'v400',
    lan: 'en',
    project: 'demo',
    user: 1, //This is also shown because it is a Path param used in the request.
  }
}

FULL plugin example

In order to show how a plugin works, the ordering team created an example of a plugin that has two filters both for users, these use the first and last names, and add a new attribute called lastname with the combination of these. This plugin also includes an extension of the API with an endpoint, this endpoint searches for users that are from a distance to another distance.

This plugin has the following folder structure:
— api
— users.php
— config.json
— filter_users_get.php
— filter_users_search.php

First of all the configuration of the plugin that is config.json:

{
  "name": "Example Ordering X",
  "description": "Description for Example Ordering",
  "author": "Ordering Inc",
  "url": "https://ordering.co",
  "version": "0.0.1",
  "hooks": {
    "actions": {},
    "filters": {
      "users_get": [
        "/filter_users_get.php"
      ],
      "users_search": [
        "/filter_users_search.php"
      ]
    }
  }
}

Because what we modify is the response of the API the hooks that are used are the filters of users_get and users_search and that executes the scripts / filter_users_get.php and / filter_users_search.php respectively.

When get user:

<?php
$body = json_decode(file_get_contents('php://input'));
$body->data->fullname = $body->data->name;
if ($body->data->lastname) $body->data->fullname .= ' '.$body->data->lastname;
echo json_encode($body->data);

knowing the structure of the answer of Ordering API for get user we use the attributes name and lastname if it exists and we concatenate them in an attribute called fullname.

When search user:

<?php
$body = json_decode(file_get_contents('php://input'));
foreach ($body->data as $user) {
	$user->fullname = $user->name;
	if ($user->lastname) $user->fullname .= ' '.$user->lastname;
}
echo json_encode($body->data);

Knowing the structure of the response of Ordering API for search user is an array, we do the same as in get users but going through the array of users.

Extending API with new endpoints

As we already know plugins can extend the functionalities to the point of being able to create new endpoints. In this example, the ordering team included an extension with an extra endpoint to search for users in a distance range. In the order of the folder the new endpoint would be the following:

GET root+'/api/user.php'

📘
root
the URL where the plugin is stored, for example yourplugin.yourdomain.com.

<?php

function distance($from, $to)
{
    $theta = $from->lng - $to->lng;
    $dist = sin(deg2rad($from->lat)) * sin(deg2rad($to->lat)) +  cos(deg2rad($from->lat)) * cos(deg2rad($to->lat)) * cos(deg2rad($theta));
    $dist = acos($dist);
    $dist = rad2deg($dist);
    $miles = $dist * 60 * 1.1515;
    return $miles * 1.609344;
}

$url = 'https://apiv4.ordering.co/v400/en/demo/users';
$user_key = 'W0X3tL5vsD4L9UouGhkqC7_vbFY6yyQzCA5phgzfhQZmxDDkCBqOGGtKlbpNnAwrW';
$cURL = curl_init();
curl_setopt($cURL, CURLOPT_URL, $url);
curl_setopt($cURL, CURLOPT_HTTPGET, true);
curl_setopt($cURL, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Accept: application/json',
    'x-api-key: '.$user_key
));
curl_setopt($cURL, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($cURL);
$result = json_decode($result);

$from = new \stdClass();
$from->lat = $_GET['lat'];
$from->lng = $_GET['lng'];
$filters = [];
foreach ($result->result as $user) {
	if ($user->location) {
		if (distance($from, $user->location) <= $_GET['max']) array_push($filters, $user);
	}
}

$result->result = $filters;

header('Content-Type: application/json');
echo json_encode($result);

📘
Permissions
It is important that an API key is sent in the header as x-api-key to have access permissions to the API requests.

Hosting on Heroku

Heroku is a platform where you can host plugins for free. The first step we must do is create an account here HEROKU and then click on sign up

After this click on new and fill in the information required to create.After this click on new and fill in the information required to create.

The next step is to add a buildpack depending on the technology we are using for this we click on 1.Settings and then 2. add buildpack

In this case we have a plugin with in PHP language

Install the Heroku CLI
Download and install the Heroku CLI.

If you haven't already, log in to your Heroku account and follow the prompts to create a new SSH public key.
$ heroku login
Create a new Git repository
Initialize a git repository in a new or existing directory
$ cd my-project/
$ git init
$ heroku git:remote -a plugin-name

You'll need to use at least an empty composer.json in your application. (for PHP)
$ echo '{}' > composer.json
Deploy your changes
Make some changes to the code you just cloned and deploy them to Heroku using Git.
$ git add .
$ git commit -m "add composer.json for PHP app detection"
$ git push heroku master

Now you can access to de plugin by the following URL:

The last step is to install the plugin by sending this URL to the resource Create Plugin

Introduction

📘
How `delay` works.

Funtions

Functioning

🚧

FULL plugin example

📘
root

📘
Permissions

Hosting on Heroku