Skip to content

rest-api.md

Latest commit

 

History

History
1354 lines (1019 loc) · 33.4 KB

rest-api.md

File metadata and controls

1354 lines (1019 loc) · 33.4 KB
Raw

Open Fixture Library API v1.0

Scroll down for example requests and responses.

Base URLs:

root

getSearchResults

POST /get-search-results

Return search results for given parameters.

Body parameter

{
  "searchQuery": "string",
  "manufacturersQuery": [
    "string"
  ],
  "categoriesQuery": [
    "string"
  ]
}

Parameters

Name In Type Required Description
searchQuery body string true none
manufacturersQuery body [string] true none
categoriesQuery body [string] true none

Example responses

200 Response

[
  {
    "key": "showtec/phantom-3r-beam",
    "name": "Showtec Phantom 3R Beam",
    "color": "#cca066"
  }
]

400 Response

{
  "error": "Some error message."
}

Responses

Status Meaning Description Schema
200 OK Fixture information for fixtures matching the queries. Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» key string true none none
» name string true none none
» color string true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

createFeedbackIssue

POST /submit-feedback

Takes the input from the client side script and creates a GitHub issue with the given feedback.

Body parameter

{
  "type": "fixture",
  "context": "string",
  "location": "string",
  "helpWanted": "string",
  "message": "string",
  "githubUsername": "string"
}

Parameters

Name In Type Required Description
type body string true none
context body string true The fixture key or plugin key.
location body string¦null true none
helpWanted body string¦null true none
message body string true none
githubUsername body string true none

Enumerated Values

Parameter Value
type fixture
type capability
type plugin

Example responses

201 Response

{
  "issueUrl": "https://github.com/OpenLightingProject/open-fixture-library/issues/1154"
}

400 Response

{
  "error": "Some error message."
}

Responses

Status Meaning Description Schema
201 Created Issue created or error occurred. Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» issueUrl string(uri)¦null true none none
» error string¦null true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
201 Content-Type string The response is JSON.
201 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
201 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

fixtures

createFixtureFromEditor

POST /fixtures/from-editor

Converts the given editor fixture data into OFL fixtures and responds with a FixtureCreateResult.

Body parameter

[
  {}
]

Example responses

201 Response

{
  "manufacturers": {
    "man-key": {
      "name": "Manufacturer name",
      "website": "https://example.org"
    }
  },
  "fixtures": {
    "man-key/fix-key": {
      "name": "Fixture name",
      "$comment": "…"
    }
  },
  "warnings": {
    "man-key/fix-key": [
      "Some warning for fixture man-key/fix-key."
    ]
  },
  "errors": {
    "man-key/fix-key": []
  }
}

Responses

Status Meaning Description Schema
201 Created Fixture successfully imported Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» manufacturers object true none none
» fixtures object true none none
» warnings object true none none
» errors object true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
201 Content-Type string The response is JSON.
201 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
201 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

importFixtureFile

POST /fixtures/import

Imports the uploaded fixture file and responds with a FixtureCreateResult.

Body parameter

{
  "plugin": "string",
  "fileName": "string",
  "fileContentBase64": "string",
  "author": "string"
}

Parameters

Name In Type Required Description
plugin body string true none
fileName body string true none
fileContentBase64 body string(base64) true none
author body string true none

Example responses

201 Response

{
  "manufacturers": {
    "man-key": {
      "name": "Manufacturer name",
      "website": "https://example.org"
    }
  },
  "fixtures": {
    "man-key/fix-key": {
      "name": "Fixture name",
      "$comment": "…"
    }
  },
  "warnings": {
    "man-key/fix-key": [
      "Some warning for fixture man-key/fix-key."
    ]
  },
  "errors": {
    "man-key/fix-key": []
  }
}

Responses

Status Meaning Description Schema
201 Created Fixture successfully imported Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» manufacturers object true none none
» fixtures object true none none
» warnings object true none none
» errors object true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
201 Content-Type string The response is JSON.
201 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
201 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

submitFixtures

POST /fixtures/submit

Creates a GitHub pull request with the given fixture data. Includes warnings, errors, GitHub username and GitHub comment in the PR description.

Body parameter

{
  "fixtureCreateResult": {
    "manufacturers": {
      "man-key": {
        "name": "Manufacturer name",
        "website": "https://example.org"
      }
    },
    "fixtures": {
      "man-key/fix-key": {
        "name": "Fixture name",
        "$comment": "…"
      }
    },
    "warnings": {
      "man-key/fix-key": [
        "Some warning for fixture man-key/fix-key."
      ]
    },
    "errors": {
      "man-key/fix-key": []
    }
  },
  "githubUsername": "string",
  "githubComment": "string"
}

Parameters

Name In Type Required Description
fixtureCreateResult body object true none
» manufacturers body object true none
» fixtures body object true none
» warnings body object true none
» errors body object true none
githubUsername body string¦null true none
githubComment body string¦null true none

Example responses

201 Response

{
  "pullRequestUrl": "http://example.com"
}

Responses

Status Meaning Description Schema
201 Created GitHub pull request created Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» pullRequestUrl string(uri) true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
201 Content-Type string The response is JSON.
201 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
201 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

getLastUpdatedFixtures

GET /fixtures/last-updated

Returns the five most recently updated fixtures.

Example responses

200 Response

[
  {
    "key": "string",
    "name": "string",
    "action": "string",
    "date": "2019-08-24",
    "color": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK Recently updated fixtures returned Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» key string true none none
» name string true none none
» action string true none none
» date string(date) true none none
» color string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

getFixtureCount

GET /fixtures/count

Returns the number of fixtures in the library.

Example responses

200 Response

{
  "count": 0
}

Responses

Status Meaning Description Schema
200 OK Fixture count returned Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» count integer true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

contributors

getRecentContributors

GET /contributors/recent

Returns the five most recent contributors.

Example responses

200 Response

[
  {
    "name": "string",
    "fixtureCount": 0,
    "latestFixtureKey": "string",
    "latestFixtureName": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK Recent contributors returned Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» name string true none none
» fixtureCount integer true none none
» latestFixtureKey string true none none
» latestFixtureName string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

manufacturers

getManufacturers

GET /manufacturers

Returns general information about all manufacturers.

Example responses

200 Response

{
  "property1": {
    "name": "string",
    "fixtureCount": 0,
    "color": "string"
  },
  "property2": {
    "name": "string",
    "fixtureCount": 0,
    "color": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK Manufacturer list returned Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» additionalProperties object false none none
»» name string true none none
»» fixtureCount integer true none none
»» color string true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

getManufacturerByKey

GET /manufacturers/{manufacturerKey}

Returns information about a specific manufacturer.

Parameters

Name In Type Required Description
manufacturerKey path string true none

Example responses

200 Response

{
  "key": "string",
  "name": "string",
  "comment": "string",
  "website": "http://example.com",
  "rdmId": 0,
  "color": "string",
  "fixtures": [
    {
      "key": "string",
      "name": "string",
      "categories": [
        "string"
      ]
    }
  ],
  "redirects": [
    {
      "key": "string",
      "redirectTo": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Manufacturer details returned Inline
400 Bad Request Bad request Inline
404 Not Found Not Found Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» key string true none none
» name string true none none
» comment string false none none
» website string(uri) false none none
» rdmId integer false none none
» color string true none none
» fixtures [object] true none none
»» key string true none none
»» name string true none none
»» categories [string] true none none
» redirects [object] true none none
»» key string true none none
»» redirectTo string true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Status Code 404

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
404 Content-Type string The response is JSON.
404 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
404 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

categories

getCategories

GET /categories

Returns general information about all fixture categories.

Example responses

200 Response

[
  {
    "name": "string",
    "fixtureCount": 0
  }
]

Responses

Status Meaning Description Schema
200 OK Category list returned Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» name string true none none
» fixtureCount integer true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

getCategoryByName

GET /categories/{categoryName}

Returns fixture information for a specific category.

Parameters

Name In Type Required Description
categoryName path string true none

Example responses

200 Response

{
  "fixtures": [
    {
      "key": "string",
      "name": "string",
      "categories": [
        "string"
      ],
      "color": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Category fixtures returned Inline
400 Bad Request Bad request Inline
404 Not Found Not Found Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» fixtures [object] true none none
»» key string true none none
»» name string true none none
»» categories [string] true none none
»» color string true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Status Code 404

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
404 Content-Type string The response is JSON.
404 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
404 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

rdm

getRdmLookup

GET /rdm

Returns the manufacturer and fixture matching the given RDM IDs.

Parameters

Name In Type Required Description
manufacturerId query integer true none
modelId query integer false none

Example responses

200 Response

{
  "manufacturerKey": "string",
  "manufacturerName": "string",
  "fixtureKey": "string"
}

Responses

Status Meaning Description Schema
200 OK RDM lookup result returned Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» manufacturerKey string¦null true none none
» manufacturerName string¦null true none none
» fixtureKey string¦null true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

plugins

getPlugins

GET /plugins

Returns general information about import and export plugins.

Example responses

200 Response

{
  "importPlugins": [
    "string"
  ],
  "exportPlugins": [
    "string"
  ],
  "data": {
    "property1": {
      "name": "string",
      "outdated": true,
      "newPlugin": "string",
      "importPluginVersion": "string",
      "exportPluginVersion": "string",
      "exportTests": [
        "string"
      ]
    },
    "property2": {
      "name": "string",
      "outdated": true,
      "newPlugin": "string",
      "importPluginVersion": "string",
      "exportPluginVersion": "string",
      "exportTests": [
        "string"
      ]
    }
  }
}

Responses

Status Meaning Description Schema
200 OK Plugin list returned Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» importPlugins [string] true none none
» exportPlugins [string] true none none
» data object true none none
»» additionalProperties object false none none
»»» name string true none none
»»» outdated boolean false none none
»»» newPlugin string false none none
»»» importPluginVersion string false none none
»»» exportPluginVersion string false none none
»»» exportTests [string] false none none

allOf

Name Type Required Restrictions Description
»»» anonymous any false none none

oneOf

Name Type Required Restrictions Description
»»»» anonymous object false none none

xor

Name Type Required Restrictions Description
»»»» anonymous any false none none

not

Name Type Required Restrictions Description
»»»»» anonymous any false none none

anyOf

Name Type Required Restrictions Description
»»»»»» anonymous object false none none

or

Name Type Required Restrictions Description
»»»»»» anonymous object false none none

and

Name Type Required Restrictions Description
»»» anonymous any false none none

oneOf

Name Type Required Restrictions Description
»»»» anonymous object false none none

xor

Name Type Required Restrictions Description
»»»» anonymous any false none none

not

Name Type Required Restrictions Description
»»»»» anonymous any false none none

anyOf

Name Type Required Restrictions Description
»»»»»» anonymous object false none none

or

Name Type Required Restrictions Description
»»»»»» anonymous object false none none

Enumerated Values

Property Value
outdated true

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

getPluginByKey

GET /plugins/{pluginKey}

Returns information about a specific import and export plugin. If an outdated plugin is requested, the information for the renamed plugin is returned.

Parameters

Name In Type Required Description
pluginKey path string true none

Example responses

200 Response

{
  "key": "string",
  "name": "string",
  "previousVersions": {
    "property1": "string",
    "property2": "string"
  },
  "description": "string",
  "links": {
    "property1": "http://example.com",
    "property2": "http://example.com"
  },
  "fixtureUsage": "string",
  "fileLocations": {
    "subDirectoriesAllowed": true,
    "property1": {
      "main": "string",
      "user": "string"
    },
    "property2": {
      "main": "string",
      "user": "string"
    }
  },
  "additionalInfo": "string",
  "helpWanted": "string",
  "exportPluginVersion": "string",
  "importPluginVersion": "string"
}

Responses

Status Meaning Description Schema
200 OK Plugin details returned Inline
400 Bad Request Bad request Inline
404 Not Found Not Found Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» key string true none none
» name string true none none
» previousVersions object true none none
»» additionalProperties string false none none
» description string true none none
» links object true none none
»» additionalProperties string(uri) false none none
» fixtureUsage string false none none
» fileLocations object false none none
»» additionalProperties object false none none
»»» main string false none none
»»» user string false none none
»» subDirectoriesAllowed boolean false none none
» additionalInfo string false none none
» helpWanted string false none none
» exportPluginVersion string false none none
» importPluginVersion string false none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none

Status Code 404

Name Type Required Restrictions Description
» error string true none none

Response Headers

Status Header Type Format Description
200 Content-Type string The response is JSON.
200 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
200 Vary string Indicates that the response varies by Origin.
400 Content-Type string The response is JSON.
400 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
400 Vary string Indicates that the response varies by Origin.
404 Content-Type string The response is JSON.
404 Access-Control-Allow-Origin string Added when the request includes an Origin header or the origin is not allowed.
404 Vary string Indicates that the response varies by Origin.
This operation does not require authentication

Schemas

FixtureCreateResult

{
  "manufacturers": {
    "man-key": {
      "name": "Manufacturer name",
      "website": "https://example.org"
    }
  },
  "fixtures": {
    "man-key/fix-key": {
      "name": "Fixture name",
      "$comment": "…"
    }
  },
  "warnings": {
    "man-key/fix-key": [
      "Some warning for fixture man-key/fix-key."
    ]
  },
  "errors": {
    "man-key/fix-key": []
  }
}

Properties

Name Type Required Restrictions Description
manufacturers object true none none
fixtures object true none none
warnings object true none none
errors object true none none

Error

{
  "error": "Some error message."
}

Properties

Name Type Required Restrictions Description
error string true none none