Creating and Managing Integrations

Each integration is located within app/Integrations/[IntegrationName]. At it's core, each integration would contain a routes file (./routes/api.php) and directory (Controllers) which will contain any controllers used by the indicated routes file. the "Example" integration is a perfect example of this.

Routing

To make sure your routes file is called within Laravel's main routing, you'll need to add it to the array within the getAPIRouteGroups() method in app/Integrations/Repositories/IntegrationRepository.php:

public function getAPIRouteGroups(){
    return [
        ...
        [
            'namespace' => 'App\Integrations\[IntegrationNamespace]\Controllers',
            'route_prefix' => '[desired-integration-route]',
            'route_path' => base_path('app/Integrations/[integration-directory]/routes/api.php'),
        ],
        ...
    ];
}

Within app/Integrations/[integration-name]/routes/api.php, you'll add the calls to the specific actions you will want your API to use, ie:

<?php
Route::get('/leads', 'LeadController@index');
Route::post('/leads', 'LeadController@store');
Route::get('/leads/{leadId}', 'LeadController@show');

Controller

When making your controller, you'll want to be sure to extend the IntegrationAPIController.php class, as it contains some useful methods in obtaining credentials and data from the request, as well as formatting and returning the proper json response from an object or collection.

<?php

namespace App\Integrations\Example\Controllers;

use App\Integrations\Abstracts\IntegrationAPIController;

class LeadController extends IntegrationAPIController
{

    public function store()
    {
        if ($this->credentials->password != 'secret') {
            throw new Exception('Invalid Password', 401);
        }
        $createdLead = LeadService::create($this->data);
        return $this->apiResponse($createdLead);
    }

}

Credentials passed to the api via the credential or credentials_raw properties are passed directly into the "credentials" property.

Similarly, the data property contains any request data sent to the api through the data property.

The controller comes with an apiResponse method, which can be passed the object or collection you want to return from the API, and this will be formatted and output accordingly.

Within your integration folder, additional directories and classes will likely be added (Services, Models etc.) to ensure your controllers handle as little logic as possible.