MIDAS API

API Usage Guide

Overview

The MIDAS API (Application Programming Interface) allows developers to interface directly with our web based scheduling software, MIDAS, from their own applications.

Installing the API

The MIDAS API is an optional add-on for MIDAS v4.03 (or later), that can be purchased along with MIDAS, or added at a later stage.
To purchase MIDAS and the API addon, please visit: https://mid.as/purchase
To add the API addon to an existing MIDAS installation, please go to MIDAS Admin Options → Manage Addons → Available Addons → API Access

Once purchased, the API will become available for one-click installation via MIDAS Admin Options → Manage Addons → Addons Ready To Install → API Access

Once installed, various API settings are available via MIDAS Admin Options → Manage Addons → Installed Addons → API Access

Making API calls

To make an API call, your application will need to perform an HTTP POST request (GET requests can also be enabled - see API Settings below) to http(s)://your_midas_url/api.pl. Each request must include as a minimum your unique API key, an API command and all associated required parameters for the API command issued. Please refer to the API Command Reference for details of available API commands and associated parameters.

Cloud-Hosted Customers: In order to ensure service quality for all hosted customers, we rate-limit connections to our servers. Therefore, please be mindful of the number & frequency of your API calls. Excessive & sustained high frequencies of API calls may result in your IP address being temporarily blocked for a short period, or permanently banned in the case of persistent abuse

API responses

The MIDAS API returns JSON (JavaScript Object Notation) formatted data. Example responses are shown throughout the API Command Reference. Error responses are also returned in JSON format and denoted by the term "error".

API Settings

A number of API settings are available via MIDAS Admin Options → Manage Addons → API Access.

MIDAS API Settings
SettingDescription
Enable API access?Enables/Disables API access. If disabled, all API calls will return:
{"error":"not enabled"}
Read Only access?With this setting enabled, the API will operate in "read-only" mode and will be prevented from making any changes to your MIDAS. If you only intend to read data from MIDAS, and not write/make changes using the API, you should select this option.
Allow GET (as well as POST) method?By default, only http POST requests to the API are permitted, and http GET requests are automatically rejected. Enabling this setting will permit either GET or POST http requests to be made to the API
Enable logging of all calls?(Only available to self-hosted editions of MIDAS) When enabled, all API calls will be logged to an api_log.dat file (located in your MIDAS directory). The format of each line of this file is as follows:

timestamp   IP_address   api_command

This can be used to log/monitor calls to your API. It should only be enabled for debugging purposes as it will reduce performance of the API, and may lead to a very large api_log.dat file if left enabled for a long of time.
API actions appear in Recent Activity log?By default when a user performs an action in MIDAS (such as adding a booking), the action is recorded in the Recent Activity log. This setting controls whether actions performed through the API that result in changes to data within MIDAS should also be included in the Recent Activity log.
Allowed ReferrersRestricts calls to your API to only those originating from certain domains/IP addresses. If left blank, API calls will be allowed from any referrer. For calls from banned referrers, the API will return:
{"error":"referrer not allowed"}

Global Parameters

The following parameters must be supplied with each API call
Required ParametersPossible ValuesDescription
keyAPI keyYour unique API key. For security, the API will only respond to your unique key. Calls made to the API without a key, or with an invalid key, will not be processed. You should not make your API key visible/available to anyone.
actionAPI commandThe action you wish the API to perform. See the API Command Reference for a full list of supported commands
The following parameters are optional, but may also be included with any API call
Optional ParametersPossible ValuesDescription
llanguage codeBy default, the API will use the "en-US" language pack where applicable. To optionally use a different language pack, its corresponding language code can be specified.
dbdatabase codeMultiple, independent, databases can be run from a single MIDAS interface. If multiple databases have been setup in your MIDAS, API calls will be made to whichever database is currently set as the "default". To make API calls to one of the other defined databases, its corresponding database code can be passed in the "db" parameter.
To locate the correct database code to pass with the "db" parameter, open up your midasglobal.dat settings file in a standard text editor and locate the <database> section within this file. This section contains details of all defined databases for your MIDAS. The database "code" to use is the current value of the "r" parameter for the relevant database
logasuser id or email addressBy default, all API calls are actioned in MIDAS under an internal "API" account. By setting the optional "logas" parameter to either the internal ID or the email address of an existing user account, API calls will instead be recorded as having been actioned under that particular user account
epoch1 | 0For API calls that require start/end times, setting "epoch" to "1" will accept start/end values in epoch seconds (instead of the default YYYYMMDDHHMM format)
For API calls that return a date/time, setting "epoch" to "1" will return date/time values in epoch seconds (instead of following the current MIDAS date/time format settings, for instance, "DD/MM/YYYY @ HH:MM")

What are epoch seconds?

Epoch seconds are the number of seconds that have elapsed since midnight Coordinated Universal Time (UTC) on 1 January 1970

Scope

Version 1.xx of the API offered a "read-only" interface to the MIDAS system, permitting data to be read, but not be added, changed, or removed.
Version 2.xx of the API provides a "bi-directional" interface to the MIDAS system, permitting data to be both read and also to be added, changed, or removed.

Test the API

The API has been enabled for testing with our on-line demo of MIDAS
You can make test API calls to the demo through the following URL: https://demo.mid.as/api.pl
The Demo API key (which must be included with your API calls) is: 797769685251f9i80MWOhwOC
NOTE: Only "read-only" calls may be made to this demo API