fredbradley / topdesk

A Laravel Service Provider for the TOPdesk API

Stars
0

TOPdesk API Service Provider

Latest Version on Packagist
Total Downloads
StyleCI Status

Primarily a Service Provider for Laravel, but this package can be used on any PHP script. It connects with a TOPdesk instance with API permissions. It uses Innovaat's package as a basis.

Early Adoptors Beware

This is intended as a wrapper for the Laravel Ecosystem for a 3rd party product TOPdesk. As such in version 2 we shall be rapidly changing the responses to deliver a resource response more native to Laravel, rather than the flat Guzzle output.

Minimum Requirements

  • PHP 7.2 or higher

Installation

Via Composer

$ composer require fredbradley/topdesk

Set up

Ensure you understand the TOPdesk API configuration and your TOPdesk environment is set up to use the API. More details can be found at developers.topdesk.com.

Without Laravel

It is my intention to release this as a framework agnostic package. But at the moment, it is only availabel for Laravel. Please submit a pull request if you fancy helping out!

With Laravel

Add three variables to your .env file

TOPdesk_endpoint="" # Your TOPdesk url, ending in "`tas/`"
TOPdesk_app_username="" # Your username you wish to authenticate with
TOPdesk_app_password="" # Your application password for that username. 

Guide

Our TOPdesk API implementation contains the following features:

  • Simple login using application passwords.
  • Automatic retry functionality that retries requests when connection errors or status codes >= 500 occur.
    We have experienced various instabilities with the TOPdesk API, and hopefully this minimizes these shortcomings.
  • Direct function calls for much used api endpoints (createIncident($params), getIncidentById($id),
    getListOfIncidents(), escalateIncidentById($id), deescalateIncidentById($id), getListOfDepartments(),
    createDepartment($params), getListOfBranches(), createBranch($params) among others).
  • Easy syntax for all other endpoints using $api->request($method, $uri, $json = [], $query = []).

Now your API should be ready to use:

$incidents = TOPDesk::getListOfIncidents([
    'start' => 0,
    'page_size' => 10
]);

foreach($incidents as $incident) {
    var_dump($incident['number']);
}

Many requests have been implemented as direct functions of the API. However, not all of them have been implemented.
For manual API requests, use the request() function:

TOPDesk::request('GET', 'api/incidents/call_types', [
    // Optional array to be sent as JSON body (for POST/PUT requests).
], [
    // Optional (search) query parameters, see API documentation for supported values.
], [
    // Optional parameters for the Guzzle request itself.
    // @see http://docs.guzzlephp.org/en/stable/request-options.html
]);

Documentation

Change log

Please see the changelog for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING.md for details and a todolist.

Security

If you discover any security related issues, please email author email instead of using the issue tracker.

Credits

License

MIT. Please see the license file for more information.