GDTF Share API

Introduction

GDTF Share provides a REST API that lets an application authenticate, view fixture revisions, and download revisions without accessing the GDTF Share website through a web browser.

Changes to the documentation

Since the GDTF Share API description was originally released, this documentation has been updated as follows:

• Improved wording, spelling, and examples
• Clarified recommended API usage
• Added general usage and attribution requirements

Use cases

This API is intended for developers who want to integrate GDTF Share functionality into their applications. Common use cases include:

• Applications that provide GDTF Share functionality without embedding a full web browser.
• Custom interfaces for logging in, listing revisions, or downloading files in consoles and other applications.
• Integration of the GDTF database into fixture type patching workflows.

Usage of the API

File server

We recommend that developers use the GDTF Share API to synchronize GDTF files with a server they operate, then serve those files to their application through their own API. The server authenticates with GDTF Share and handles synchronization, so end users do not need to log in to GDTF Share individually. This approach can reduce traffic to GDTF Share, limit the information it receives about end users’ IP addresses, geolocation, and usage, and reduce the application’s dependence on GDTF Share availability. Applications may also connect directly to GDTF Share; in that case, each user must authenticate with their own GDTF Share account.

Caching

Temporary caching of GDTF files is permitted. Keep cached files up to date: the cache must not be more than 24 hours old. To help avoid overloading GDTF Share infrastructure, we recommend refreshing the cache approximately every 120 minutes.

Listing and Search

When listing GDTF files, you must use the uploader field returned by the Get List function to identify and clearly label each file. This allows users to distinguish files provided by manufacturers from files created by users.

When providing search across GDTF files, you must search both the Name and LongName fields. Searching LongName as well as Name helps users find files whose names contain special characters.

Attribution

When using GDTF files in your application, you must provide attribution. Include the credit “Powered by GDTF” in the product user manual, digital About screen, or accompanying technical documentation, and display the GDTF logo alongside the credit:

Reporting GDTF Share API Issues

To report an issue with the GDTF Share API, use the contact form and select “Problems or Issues.”

API functions

• Login: Authenticate with a GDTF Share username and password.
• Get List: Retrieve a list of revisions.
• Download: Download a file by its revision ID.

Each function is described in the Functions section.

Requirements

GDTF Share User Account

A GDTF Share account is required for each client that authenticates directly with the API. If your application connects directly, each user must use their own account. If your application gets files from your sync server, only the server needs to authenticate with GDTF Share; end users do not need individual GDTF Share accounts. Users who need an account can sign up for a free GDTF Share account.

Software

To use the API, you need an HTTP client, such as curl, available on many operating systems and platforms. For an introduction to web APIs, see the MDN Web API documentation.

Cookies

A session cookie is required to authenticate API requests. Include the cookie with each subsequent request; requests without it will not be authenticated. The cookie expires after two hours of inactivity, after which the account used by the API client must log in again.

The sample requests show how to use a cookie file with curl. For more information about cookies, see MDN’s guide to HTTP cookies.

Functions

Login

Use this function to authenticate with a username and password.

Parameters

Response

Sample request

curl -c session.txt -L -X POST https://gdtf-share.com/apis/public/login.php \
        -H 'Content-Type: application/json' \
        -d '{"user":"<username>", "password":"<password>"}'

Sample response

On success: HTTP status code 200

{ "result": true, "notice": "Welcome! Why did the coffee file a police report?  It got mugged." }

On error: HTTP status code 401

{ "result": false, "error": "No valid user or password provided." }

Get List

Use this function to retrieve the list of revisions.

Parameters

This function does not require any parameters.

Response

Sample request

curl -b session.txt https://gdtf-share.com/apis/public/getList.php

Sample response

On success: HTTP status code 200

{ "result": true, "list": [<array>] }

On error: HTTP status code 401

{ "result": false, "error": "Unauthorized." }

The list property in the response is an array. Each array element has the following format:

{
  "rid": 12345,
  "fixture": "Example Fixture",
  "manufacturer": "Example Manufacturer",
  "revision": "Example revision",
  "creationDate": "1570494396",
  "lastModified": "1570494396",
  "uploader": "Manuf.",
  "rating": "4.1",
  "version": "1.0",
  "creator": "Real User 42",
  "uuid": "AAAAAAAA-3545-4C7C-ACA2-AAAAAAAAAAAA",
  "filesize": 4809117,
  "modes": [
    { "name": "mode1", "dmxfootprint": 49 },
    { "name": "mode2", "dmxfootprint": 52 }
  ]
}

Response definitions

The following table describes the fields in each response item.

Each entry in the modes array contains the following items:

File download

Use this function to download a single file.

Parameters

Response

On success, the response contains the file as a binary stream. On error, the response contains a JSON object with an error message. Use the HTTP status code to determine whether the download succeeded.

Sample request

curl -b session.txt "https://gdtf-share.com/apis/public/downloadFile.php?rid=12345" \
    --output file.gdtf

Sample response

On success: HTTP status code 200

The file is saved as file.gdtf.

On error: HTTP status code 404

{ "result": false, "error": "File does not exist." }