Skip to content

rest-api.md

Latest commit

 

History

History
733 lines (565 loc) · 15.6 KB

rest-api.md

File metadata and controls

733 lines (565 loc) · 15.6 KB

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

[
  "showtec/phantom-3r-beam",
  "showtec/phantom-50-led-spot",
  "showtec/phantom-140-led-spot",
  "showtec/phantom-matrix-fx"
]

Responses

Status Meaning Description Schema
200 OK Fixture keys matching the queries. Inline

Response Schema

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"
}

Responses

Status Meaning Description Schema
201 Created Issue created or error occured. Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» issueUrl string¦null true none none
» error string¦null true none none
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
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
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": "string"
}

Responses

Status Meaning Description Schema
201 Created OK Inline
400 Bad Request Bad request Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» pullRequestUrl string true none none

Status Code 400

Name Type Required Restrictions Description
» error string true none none
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 none 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
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": "string",
  "rdmId": 0,
  "color": "string",
  "fixtures": [
    {
      "key": "string",
      "name": "string",
      "categories": [
        "string"
      ]
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK none 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 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] false none none

Status Code 404

Name Type Required Restrictions Description
» error string true none none
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": null,
      "newPlugin": "string",
      "importPluginVersion": "string",
      "exportPluginVersion": "string",
      "exportTests": [
        "string"
      ]
    },
    "property2": {
      "name": "string",
      "outdated": null,
      "newPlugin": "string",
      "importPluginVersion": "string",
      "exportPluginVersion": "string",
      "exportTests": [
        "string"
      ]
    }
  }
}

Responses

Status Meaning Description Schema
200 OK none 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 any false none none
»»» newPlugin string false none none
»»» importPluginVersion string false none none
»»» exportPluginVersion string false none none
»»» exportTests [string] false none none
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": "string",
    "property2": "string"
  },
  "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 none 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 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 404

Name Type Required Restrictions Description
» error string true none none
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