Service Registry REST Documentation

General Notes

All paths above are relative to the REST endpoint base

Read methods

Method / Path:	GET /activeJobs.json
Description:	Returns all active jobs as JSON.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	application/json
Status codes:	`200: OK`, Active jobs found.
Returned Entity Schema:	Click to view <?xml version="1.0" standalone="yes"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="job" type="tns:job"/> <xs:element name="jobs" type="tns:jobs"/> <xs:complexType name="jobs"> <xs:sequence> <xs:element ref="tns:job" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="job"> <xs:sequence> <xs:element name="creator" type="xs:string" minOccurs="0"/> <xs:element name="organization" type="xs:string" minOccurs="0"/> <xs:element name="url" type="xs:string" minOccurs="0"/> <xs:element name="operation" type="xs:string" minOccurs="0"/> <xs:element name="args" minOccurs="0"> <xs:complexType> <xs:sequence> <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="createdHost" type="xs:string" minOccurs="0"/> <xs:element name="processingHost" type="xs:string" minOccurs="0"/> <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/> <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/> <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/> <xs:element name="parentJobId" type="xs:long" minOccurs="0"/> <xs:element name="rootJobId" type="xs:long" minOccurs="0"/> <xs:element name="queueTime" type="xs:long" minOccurs="0"/> <xs:element name="runTime" type="xs:long" minOccurs="0"/> <xs:element name="payload" type="xs:string" minOccurs="0"/> <xs:element name="dispatchable" type="xs:boolean"/> <xs:element name="jobLoad" type="xs:float" minOccurs="0"/> </xs:sequence> <xs:attribute name="id" type="xs:long" use="required"/> <xs:attribute name="version" type="xs:long" use="required"/> <xs:attribute name="type" type="xs:string"/> <xs:attribute name="status" type="tns:status"/> </xs:complexType> <xs:simpleType name="status"> <xs:restriction base="xs:string"> <xs:enumeration value="QUEUED"/> <xs:enumeration value="PAUSED"/> <xs:enumeration value="RUNNING"/> <xs:enumeration value="FINISHED"/> <xs:enumeration value="FAILED"/> <xs:enumeration value="DELETED"/> <xs:enumeration value="INSTANTIATED"/> <xs:enumeration value="DISPATCHING"/> <xs:enumeration value="RESTART"/> <xs:enumeration value="CANCELLED"/> <xs:enumeration value="WAITING"/> </xs:restriction> </xs:simpleType> </xs:schema> Hide
Notes:	Return value description: A list of active jobs as JSON
Testing:	Sample: `/activeJobs.json` /services/activeJobs.json

Method / Path:	GET /activeJobs.xml
Description:	Returns all active jobs as XML.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/xml
Status codes:	`200: OK`, Active jobs found.
Returned Entity Schema:	Click to view <?xml version="1.0" standalone="yes"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="job" type="tns:job"/> <xs:element name="jobs" type="tns:jobs"/> <xs:complexType name="jobs"> <xs:sequence> <xs:element ref="tns:job" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="job"> <xs:sequence> <xs:element name="creator" type="xs:string" minOccurs="0"/> <xs:element name="organization" type="xs:string" minOccurs="0"/> <xs:element name="url" type="xs:string" minOccurs="0"/> <xs:element name="operation" type="xs:string" minOccurs="0"/> <xs:element name="args" minOccurs="0"> <xs:complexType> <xs:sequence> <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="createdHost" type="xs:string" minOccurs="0"/> <xs:element name="processingHost" type="xs:string" minOccurs="0"/> <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/> <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/> <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/> <xs:element name="parentJobId" type="xs:long" minOccurs="0"/> <xs:element name="rootJobId" type="xs:long" minOccurs="0"/> <xs:element name="queueTime" type="xs:long" minOccurs="0"/> <xs:element name="runTime" type="xs:long" minOccurs="0"/> <xs:element name="payload" type="xs:string" minOccurs="0"/> <xs:element name="dispatchable" type="xs:boolean"/> <xs:element name="jobLoad" type="xs:float" minOccurs="0"/> </xs:sequence> <xs:attribute name="id" type="xs:long" use="required"/> <xs:attribute name="version" type="xs:long" use="required"/> <xs:attribute name="type" type="xs:string"/> <xs:attribute name="status" type="tns:status"/> </xs:complexType> <xs:simpleType name="status"> <xs:restriction base="xs:string"> <xs:enumeration value="QUEUED"/> <xs:enumeration value="PAUSED"/> <xs:enumeration value="RUNNING"/> <xs:enumeration value="FINISHED"/> <xs:enumeration value="FAILED"/> <xs:enumeration value="DELETED"/> <xs:enumeration value="INSTANTIATED"/> <xs:enumeration value="DISPATCHING"/> <xs:enumeration value="RESTART"/> <xs:enumeration value="CANCELLED"/> <xs:enumeration value="WAITING"/> </xs:restriction> </xs:simpleType> </xs:schema> Hide
Notes:	Return value description: A list of active jobs as XML
Testing:	Sample: `/activeJobs.xml` /services/activeJobs.xml

Method / Path: GET /available.json

Description: Lists available services by service type identifier, ordered by load.

Path params: NONE

Optional (query) params: serviceType: The service type identifier

Response formats: application/json

Status codes: 200: OK, Returned the available services.
400: Bad Request, No service type specified, bad request.

Notes:

Return value description: The services list as JSON

Testing:

Sample: /available.json?serviceType={serviceType}

Testing form (click to reveal)

Method / Path: GET /available.xml

Description: Lists available services by service type identifier, ordered by load.

Path params: NONE

Optional (query) params: serviceType: The service type identifier

Response formats: text/xml

Status codes: 200: OK, Returned the available services.
400: Bad Request, No service type specified, bad request.

Notes:

Return value description: The services list as XML

Testing:

Sample: /available.xml?serviceType={serviceType}

Testing form (click to reveal)

Method / Path: GET /job/{id}/children.json

Description: Returns all children from a job as JSON.

Path params: id: The parent job identifier

Optional (query) params: NONE

Response formats: application/json

Status codes: 200: OK, Jobs found.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="job" type="tns:job"/>

  <xs:element name="jobs" type="tns:jobs"/>

  <xs:complexType name="jobs">
    <xs:sequence>
      <xs:element ref="tns:job" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="job">
    <xs:sequence>
      <xs:element name="creator" type="xs:string" minOccurs="0"/>
      <xs:element name="organization" type="xs:string" minOccurs="0"/>
      <xs:element name="url" type="xs:string" minOccurs="0"/>
      <xs:element name="operation" type="xs:string" minOccurs="0"/>
      <xs:element name="args" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="createdHost" type="xs:string" minOccurs="0"/>
      <xs:element name="processingHost" type="xs:string" minOccurs="0"/>
      <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="parentJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="rootJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="queueTime" type="xs:long" minOccurs="0"/>
      <xs:element name="runTime" type="xs:long" minOccurs="0"/>
      <xs:element name="payload" type="xs:string" minOccurs="0"/>
      <xs:element name="dispatchable" type="xs:boolean"/>
      <xs:element name="jobLoad" type="xs:float" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:long" use="required"/>
    <xs:attribute name="version" type="xs:long" use="required"/>
    <xs:attribute name="type" type="xs:string"/>
    <xs:attribute name="status" type="tns:status"/>
  </xs:complexType>

  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="QUEUED"/>
      <xs:enumeration value="PAUSED"/>
      <xs:enumeration value="RUNNING"/>
      <xs:enumeration value="FINISHED"/>
      <xs:enumeration value="FAILED"/>
      <xs:enumeration value="DELETED"/>
      <xs:enumeration value="INSTANTIATED"/>
      <xs:enumeration value="DISPATCHING"/>
      <xs:enumeration value="RESTART"/>
      <xs:enumeration value="CANCELLED"/>
      <xs:enumeration value="WAITING"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: A list of children jobs as JSON

Testing:

Sample: /job/{id}/children.json

Testing form (click to reveal)

Method / Path: GET /job/{id}/children.xml

Description: Returns all children from a job as XML.

Path params: id: The parent job identifier

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, Jobs found.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="job" type="tns:job"/>

  <xs:element name="jobs" type="tns:jobs"/>

  <xs:complexType name="jobs">
    <xs:sequence>
      <xs:element ref="tns:job" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="job">
    <xs:sequence>
      <xs:element name="creator" type="xs:string" minOccurs="0"/>
      <xs:element name="organization" type="xs:string" minOccurs="0"/>
      <xs:element name="url" type="xs:string" minOccurs="0"/>
      <xs:element name="operation" type="xs:string" minOccurs="0"/>
      <xs:element name="args" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="createdHost" type="xs:string" minOccurs="0"/>
      <xs:element name="processingHost" type="xs:string" minOccurs="0"/>
      <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="parentJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="rootJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="queueTime" type="xs:long" minOccurs="0"/>
      <xs:element name="runTime" type="xs:long" minOccurs="0"/>
      <xs:element name="payload" type="xs:string" minOccurs="0"/>
      <xs:element name="dispatchable" type="xs:boolean"/>
      <xs:element name="jobLoad" type="xs:float" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:long" use="required"/>
    <xs:attribute name="version" type="xs:long" use="required"/>
    <xs:attribute name="type" type="xs:string"/>
    <xs:attribute name="status" type="tns:status"/>
  </xs:complexType>

  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="QUEUED"/>
      <xs:enumeration value="PAUSED"/>
      <xs:enumeration value="RUNNING"/>
      <xs:enumeration value="FINISHED"/>
      <xs:enumeration value="FAILED"/>
      <xs:enumeration value="DELETED"/>
      <xs:enumeration value="INSTANTIATED"/>
      <xs:enumeration value="DISPATCHING"/>
      <xs:enumeration value="RESTART"/>
      <xs:enumeration value="CANCELLED"/>
      <xs:enumeration value="WAITING"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: A list of children jobs as XML

Testing:

Sample: /job/{id}/children.xml

Testing form (click to reveal)

Method / Path: GET /count

Description: Returns the number of jobs matching the query parameters as plain text.

Path params: NONE

Optional (query) params: serviceType: The service type identifier
status: The job status
host: The host executing the job
operation: The job's operation

Response formats: text/plain

Status codes: 200: OK, Job count returned.

Notes:

Return value description: The number of matching jobs

Testing:

Sample: /count?serviceType={serviceType}&status={status}&host={host}&operation={operation}

Testing form (click to reveal)

Method / Path:	GET /currentload
Description:	Returns the current load on the servers in this service registry. If there is only one server in this service registry this will be the the load that one server. If it is a distributed install across many servers then this number will be a dictionary of the load on all nodes in the cluster.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/xml
Status codes:	`200: OK`, Current load for the cluster.
Notes:	Return value description: The current load across the cluster
Testing:	Sample: `/currentload` /services/currentload

Method / Path: GET /health.json

Description: Checks the status of the registered services

Path params: NONE

Optional (query) params: serviceType: The service type identifier
host: The host, including the http(s) protocol

Response formats: application/json

Status codes: 200: OK, Service states returned
404: Not Found, No service of that type on that host is registered.
503: Service Unavailable, An error has occurred during stats processing

Notes:

Return value description: Returns NO_CONTENT if services are in a proper state

Testing:

Sample: /health.json?serviceType={serviceType}&host={host}

Testing form (click to reveal)

Method / Path: GET /health.xml

Description: Checks the status of the registered services

Path params: NONE

Optional (query) params: serviceType: The service type identifier
host: The host, including the http(s) protocol

Response formats: application/xml

Status codes: 200: OK, Service states returned
404: Not Found, No service of that type on that host is registered.
503: Service Unavailable, An error has occurred during stats processing

Notes:

Return value description: Returns NO_CONTENT if services are in a proper state

Testing:

Sample: /health.xml?serviceType={serviceType}&host={host}

Testing form (click to reveal)

Method / Path:	GET /hosts.json
Description:	Returns a host registraton or list of available host registrations as JSON.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	application/json
Status codes:	`200: OK`, Returned the available hosts.
Returned Entity Schema:	Click to view <?xml version="1.0" standalone="yes"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://serviceregistry.opencastproject.org" xmlns:tns="http://serviceregistry.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="host" type="tns:host"/> <xs:element name="hosts" type="tns:hosts"/> <xs:complexType name="hosts"> <xs:sequence> <xs:element ref="tns:host" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="host"> <xs:sequence> <xs:element name="base_url" type="xs:string" minOccurs="0"/> <xs:element name="address" type="xs:string" minOccurs="0"/> <xs:element name="node_name" type="xs:string" minOccurs="0"/> <xs:element name="memory" type="xs:long"/> <xs:element name="cores" type="xs:int"/> <xs:element name="max_load" type="xs:float"/> <xs:element name="online" type="xs:boolean"/> <xs:element name="active" type="xs:boolean"/> <xs:element name="maintenance" type="xs:boolean"/> </xs:sequence> </xs:complexType> </xs:schema> Hide
Notes:	Return value description: The host list as JSON
Testing:	Sample: `/hosts.json` /services/hosts.json

Method / Path:	GET /hosts.xml
Description:	Returns a host registraton or list of available host registrations as XML.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/xml
Status codes:	`200: OK`, Returned the available hosts.
Returned Entity Schema:	Click to view <?xml version="1.0" standalone="yes"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://serviceregistry.opencastproject.org" xmlns:tns="http://serviceregistry.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="host" type="tns:host"/> <xs:element name="hosts" type="tns:hosts"/> <xs:complexType name="hosts"> <xs:sequence> <xs:element ref="tns:host" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="host"> <xs:sequence> <xs:element name="base_url" type="xs:string" minOccurs="0"/> <xs:element name="address" type="xs:string" minOccurs="0"/> <xs:element name="node_name" type="xs:string" minOccurs="0"/> <xs:element name="memory" type="xs:long"/> <xs:element name="cores" type="xs:int"/> <xs:element name="max_load" type="xs:float"/> <xs:element name="online" type="xs:boolean"/> <xs:element name="active" type="xs:boolean"/> <xs:element name="maintenance" type="xs:boolean"/> </xs:sequence> </xs:complexType> </xs:schema> Hide
Notes:	Return value description: The host list as XML
Testing:	Sample: `/hosts.xml` /services/hosts.xml

Method / Path: GET /job/{id}.json

Description: Returns a job as JSON.

Path params: id: The job identifier

Optional (query) params: NONE

Response formats: application/json

Status codes: 200: OK, Job found.
404: Not Found, No job with that identifier exists.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="job" type="tns:job"/>

  <xs:complexType name="job">
    <xs:sequence>
      <xs:element name="creator" type="xs:string" minOccurs="0"/>
      <xs:element name="organization" type="xs:string" minOccurs="0"/>
      <xs:element name="url" type="xs:string" minOccurs="0"/>
      <xs:element name="operation" type="xs:string" minOccurs="0"/>
      <xs:element name="args" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="createdHost" type="xs:string" minOccurs="0"/>
      <xs:element name="processingHost" type="xs:string" minOccurs="0"/>
      <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="parentJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="rootJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="queueTime" type="xs:long" minOccurs="0"/>
      <xs:element name="runTime" type="xs:long" minOccurs="0"/>
      <xs:element name="payload" type="xs:string" minOccurs="0"/>
      <xs:element name="dispatchable" type="xs:boolean"/>
      <xs:element name="jobLoad" type="xs:float" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:long" use="required"/>
    <xs:attribute name="version" type="xs:long" use="required"/>
    <xs:attribute name="type" type="xs:string"/>
    <xs:attribute name="status" type="tns:status"/>
  </xs:complexType>

  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="QUEUED"/>
      <xs:enumeration value="PAUSED"/>
      <xs:enumeration value="RUNNING"/>
      <xs:enumeration value="FINISHED"/>
      <xs:enumeration value="FAILED"/>
      <xs:enumeration value="DELETED"/>
      <xs:enumeration value="INSTANTIATED"/>
      <xs:enumeration value="DISPATCHING"/>
      <xs:enumeration value="RESTART"/>
      <xs:enumeration value="CANCELLED"/>
      <xs:enumeration value="WAITING"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: The job as JSON

Testing:

Sample: /job/{id}.json

Testing form (click to reveal)

Method / Path: GET /job/{id}.xml

Description: Returns a job as XML.

Path params: id: The job identifier

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, Job found.
404: Not Found, No job with that identifier exists.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://job.opencastproject.org" xmlns:tns="http://job.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="job" type="tns:job"/>

  <xs:complexType name="job">
    <xs:sequence>
      <xs:element name="creator" type="xs:string" minOccurs="0"/>
      <xs:element name="organization" type="xs:string" minOccurs="0"/>
      <xs:element name="url" type="xs:string" minOccurs="0"/>
      <xs:element name="operation" type="xs:string" minOccurs="0"/>
      <xs:element name="args" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="arg" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="createdHost" type="xs:string" minOccurs="0"/>
      <xs:element name="processingHost" type="xs:string" minOccurs="0"/>
      <xs:element name="dateCreated" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateStarted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="dateCompleted" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="parentJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="rootJobId" type="xs:long" minOccurs="0"/>
      <xs:element name="queueTime" type="xs:long" minOccurs="0"/>
      <xs:element name="runTime" type="xs:long" minOccurs="0"/>
      <xs:element name="payload" type="xs:string" minOccurs="0"/>
      <xs:element name="dispatchable" type="xs:boolean"/>
      <xs:element name="jobLoad" type="xs:float" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="id" type="xs:long" use="required"/>
    <xs:attribute name="version" type="xs:long" use="required"/>
    <xs:attribute name="type" type="xs:string"/>
    <xs:attribute name="status" type="tns:status"/>
  </xs:complexType>

  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="QUEUED"/>
      <xs:enumeration value="PAUSED"/>
      <xs:enumeration value="RUNNING"/>
      <xs:enumeration value="FINISHED"/>
      <xs:enumeration value="FAILED"/>
      <xs:enumeration value="DELETED"/>
      <xs:enumeration value="INSTANTIATED"/>
      <xs:enumeration value="DISPATCHING"/>
      <xs:enumeration value="RESTART"/>
      <xs:enumeration value="CANCELLED"/>
      <xs:enumeration value="WAITING"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: The job as XML

Testing:

Sample: /job/{id}.xml

Testing form (click to reveal)

Method / Path:	GET /maxconcurrentjobs
Description:	Returns the number of jobs that the servers in this service registry can execute concurrently. If there is only one server in this service registry this will be the number of jobs that one server is able to do at one time. If it is a distributed install across many servers then this number will be the total number of jobs the cluster can process concurrently.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/plain
Status codes:	`200: OK`, Maximum number of concurrent jobs returned.
Notes:	Return value description: The maximum number of concurrent jobs
Testing:	Sample: `/maxconcurrentjobs` /services/maxconcurrentjobs

Method / Path: GET /maxload

Description: Returns the maximum load that servers in this service registry can execute concurrently. If there is only one server in this service registry this will be the maximum load that one server is able to handle at one time. If it is a distributed install across many servers then this number will be the maximum load the cluster can process concurrently.

Path params: NONE

Optional (query) params: host: The host you want to know the maximum load for.

Response formats: text/xml

Status codes: 200: OK, Maximum load for the cluster.

Notes:

Return value description: The maximum load of the cluster or server

Testing:

Sample: /maxload?host={host}

Testing form (click to reveal)

Method / Path:	GET /ownload
Description:	Returns the current load on this service registry's node.
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/plain
Status codes:	`200: OK`, Current load for the cluster.
Notes:	Return value description: The current load across the cluster
Testing:	Sample: `/ownload` /services/ownload

Method / Path: GET /services.json

Description: Returns a service registraton or list of available service registrations as JSON.

Path params: NONE

Optional (query) params: serviceType: The service type identifier
host: The host, including the http(s) protocol

Response formats: application/json

Status codes: 200: OK, Returned the available service.
404: Not Found, No service of that type on that host is registered.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://serviceregistry.opencastproject.org" xmlns:tns="http://serviceregistry.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="service" type="tns:service"/>

  <xs:element name="services" type="tns:services"/>

  <xs:complexType name="services">
    <xs:sequence>
      <xs:element ref="tns:service" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="service">
    <xs:sequence>
      <xs:element name="type" type="xs:string" minOccurs="0"/>
      <xs:element name="host" type="xs:string" minOccurs="0"/>
      <xs:element name="path" type="xs:string" minOccurs="0"/>
      <xs:element name="active" type="xs:boolean"/>
      <xs:element name="online" type="xs:boolean"/>
      <xs:element name="maintenance" type="xs:boolean"/>
      <xs:element name="jobproducer" type="xs:boolean"/>
      <xs:element name="onlinefrom" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="service_state" type="tns:serviceState" minOccurs="0"/>
      <xs:element name="state_changed" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="error_state_trigger" type="xs:int"/>
      <xs:element name="warning_state_trigger" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="serviceState">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NORMAL"/>
      <xs:enumeration value="WARNING"/>
      <xs:enumeration value="ERROR"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: The services list as XML

Testing:

Sample: /services.json?serviceType={serviceType}&host={host}

Testing form (click to reveal)

Method / Path: GET /services.xml

Description: Returns a service registraton or list of available service registrations as XML.

Path params: NONE

Optional (query) params: serviceType: The service type identifier
host: The host, including the http(s) protocol

Response formats: text/xml

Status codes: 200: OK, Returned the available service.
404: Not Found, No service of that type on that host is registered.

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://serviceregistry.opencastproject.org" xmlns:tns="http://serviceregistry.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="service" type="tns:service"/>

  <xs:element name="services" type="tns:services"/>

  <xs:complexType name="services">
    <xs:sequence>
      <xs:element ref="tns:service" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="service">
    <xs:sequence>
      <xs:element name="type" type="xs:string" minOccurs="0"/>
      <xs:element name="host" type="xs:string" minOccurs="0"/>
      <xs:element name="path" type="xs:string" minOccurs="0"/>
      <xs:element name="active" type="xs:boolean"/>
      <xs:element name="online" type="xs:boolean"/>
      <xs:element name="maintenance" type="xs:boolean"/>
      <xs:element name="jobproducer" type="xs:boolean"/>
      <xs:element name="onlinefrom" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="service_state" type="tns:serviceState" minOccurs="0"/>
      <xs:element name="state_changed" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="error_state_trigger" type="xs:int"/>
      <xs:element name="warning_state_trigger" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="serviceState">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NORMAL"/>
      <xs:enumeration value="WARNING"/>
      <xs:enumeration value="ERROR"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: The services list as XML

Testing:

Sample: /services.xml?serviceType={serviceType}&host={host}

Testing form (click to reveal)

Method / Path:	GET /statistics.json
Description:	List the service registrations in the cluster, along with some simple statistics
Path params:	NONE
Optional (query) params:	NONE
Response formats:	application/json
Status codes:	`200: OK`, A JSON representation of the service statistics
Notes:	Return value description: The service statistics.
Testing:	Sample: `/statistics.json` /services/statistics.json

Method / Path:	GET /statistics.xml
Description:	List the service registrations in the cluster, along with some simple statistics
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/xml
Status codes:	`200: OK`, An XML representation of the service statistics
Notes:	Return value description: The service statistics.
Testing:	Sample: `/statistics.xml` /services/statistics.xml

Write methods

Method / Path: POST /job

Description: Creates a new job.

Path params: NONE

Required (form) params: jobType: The job type identifier
host: The creating host, including the http(s) protocol
operation: The operation this job should execute

Optional (form) params: payload: The job type identifier
start: Whether the job should be queued for dispatch and execution
jobLoad: The load this job will incur on the system
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation

Response formats: text/xml

Status codes: 201: Created, Job created.
400: Bad Request, The required parameters were not supplied, bad request.

Notes:

Return value description: An XML representation of the job.

Testing:

Sample: /job

Testing form (click to reveal)

Form action: /services/job

* jobType:		The job type identifier
* host:		The creating host, including the http(s) protocol
* operation:		The operation this job should execute
payload: The job type identifier
start:		Whether the job should be queued for dispatch and execution
jobLoad:		The load this job will incur on the system
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation
arg: An argument for the operation

Response:

Method / Path: DELETE /job/{id}

Description: Deletes a job from the service registry

Path params: id(Default value=0): ID of the job to delete

Optional (query) params: NONE

Status codes: 204: No Content, Job successfully deleted
404: Not Found, Job with given id could not be found

Notes:

Return value description: No data is returned, just the HTTP status code

Testing:

Sample: /job/{id}

Testing form (click to reveal)

Method / Path: POST /disablehost

Description: Disable a server from the cluster.

Path params: NONE

Required (form) params: host: The host name, including the http(s) protocol

Optional (form) params: NONE

Status codes: 204: No Content, The host was disabled successfully
404: Not Found, The host does not exist

Notes:

Return value description: No content.

Testing:

Sample: /disablehost

Testing form (click to reveal)

Method / Path: POST /enablehost

Description: Enable a server from the cluster.

Path params: NONE

Required (form) params: host: The host name, including the http(s) protocol

Optional (form) params: NONE

Status codes: 204: No Content, The host was enabled successfully
404: Not Found, The host does not exist

Notes:

Return value description: No content.

Testing:

Sample: /enablehost

Testing form (click to reveal)

Method / Path: POST /maintenance

Description: Sets the maintenance status for a server in the cluster.

Path params: NONE

Required (form) params: host: The host name, including the http(s) protocol
maintenance: Whether this host should be put into maintenance mode (true) or not

Optional (form) params: NONE

Status codes: 204: No Content, The host was registered successfully
404: Not Found, Host not found

Notes:

Return value description: No content.

Testing:

Sample: /maintenance

Testing form (click to reveal)

Method / Path: POST /register

Description: Add a new service registration to the cluster.

Path params: NONE

Required (form) params: serviceType: The service type identifier
host: The host providing the service, including the http(s) protocol
path: The service path on the host
jobProducer: Whether this service is a producer of long running jobs requiring dispatch

Optional (form) params: NONE

Response formats: text/xml

Status codes: 200: OK, An XML representation of the new service registration

Returned Entity Schema:

Click to view

<?xml version="1.0" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="http://serviceregistry.opencastproject.org" xmlns:tns="http://serviceregistry.opencastproject.org" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="service" type="tns:service"/>

  <xs:complexType name="service">
    <xs:sequence>
      <xs:element name="type" type="xs:string" minOccurs="0"/>
      <xs:element name="host" type="xs:string" minOccurs="0"/>
      <xs:element name="path" type="xs:string" minOccurs="0"/>
      <xs:element name="active" type="xs:boolean"/>
      <xs:element name="online" type="xs:boolean"/>
      <xs:element name="maintenance" type="xs:boolean"/>
      <xs:element name="jobproducer" type="xs:boolean"/>
      <xs:element name="onlinefrom" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="service_state" type="tns:serviceState" minOccurs="0"/>
      <xs:element name="state_changed" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="error_state_trigger" type="xs:int"/>
      <xs:element name="warning_state_trigger" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="serviceState">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NORMAL"/>
      <xs:enumeration value="WARNING"/>
      <xs:enumeration value="ERROR"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Notes:

Return value description: The service registration.

Testing:

Sample: /register

Testing form (click to reveal)

Method / Path: POST /registerhost

Description: Add a new server to the cluster.

Path params: NONE

Required (form) params: host: The host name, including the http(s) protocol
address: The IP address
nodeName: Descriptive node name
memory: The allocated memory
cores: The available cores
maxLoad: The maximum load this host support

Optional (form) params: NONE

Status codes: 204: No Content, The host was registered successfully

Notes:

Return value description: No content.

Testing:

Sample: /registerhost

Testing form (click to reveal)

Method / Path: POST /removejobs

Description: Removes all given jobs and their child jobs

Path params: NONE

Required (form) params: jobIds: The IDs of the jobs to delete

Optional (form) params: NONE

Status codes: 204: No Content, Jobs successfully removed
500: Internal Server Error, Error while removing jobs

Notes:

Return value description: No data is returned, just the HTTP status code

Testing:

Sample: /removejobs

Testing form (click to reveal)

Method / Path: POST /removeparentlessjobs

Description: Removes all jobs without a parent job which have passed their lifetime

Path params: NONE

Required (form) params: lifetime: Lifetime of parentless jobs

Optional (form) params: NONE

Status codes: 204: No Content, Parentless jobs successfully removed
500: Internal Server Error, Error while removing parentless jobs

Notes:

Return value description: No data is returned, just the HTTP status code

Testing:

Sample: /removeparentlessjobs

Testing form (click to reveal)

Method / Path: POST /sanitize

Description: Sets the given service to NORMAL state

Path params: NONE

Required (form) params: serviceType: The service type identifier
host: The host providing the service, including the http(s) protocol

Optional (form) params: NONE

Status codes: 204: No Content, The service was successfully sanitized
404: Not Found, No service of that type on that host is registered.

Notes:

Return value description: No content

Testing:

Sample: /sanitize

Testing form (click to reveal)

Method / Path: POST /unregister

Description: Removes a service registration.

Path params: NONE

Required (form) params: serviceType: The service type identifier
host: The host providing the service, including the http(s) protocol

Optional (form) params: NONE

Status codes: 204: No Content, The service was unregistered successfully

Notes:

Return value description: No content

Testing:

Sample: /unregister

Testing form (click to reveal)

Method / Path: POST /unregisterhost

Description: Removes a server from the cluster.

Path params: NONE

Required (form) params: host: The host name, including the http(s) protocol

Optional (form) params: NONE

Status codes: 204: No Content, The host was removed successfully

Notes:

Return value description: No content.

Testing:

Sample: /unregisterhost

Testing form (click to reveal)

Method / Path: PUT /job/{id}.xml

Description: Updates an existing job

Path params: id: The job identifier

Required (form) params: job: The updated job as XML

Optional (form) params: NONE

Response formats: text/xml

Status codes: 204: No Content, Job updated.
404: Not Found, Job not found.

Notes:

Return value description: No content

Testing:

Sample: /job/{id}.xml

Testing form (click to reveal)

Service Registry REST Documentation

General Notes

Table of Contents

Read methods

Write methods