ARC CE REST interface specification

Note

The current interface version is 1.1

The REST API endpoint

The various functionalities of the service are accessible through HTTP(S) URL built upon following pattern:

<service endpoint URL> represents mounting point of the service and may look like https://arc.example.org:443/arex.

<version> is two parts number separated by dot. Current version is 1.1.

<functionality> is one of keywords defined below.

Further the part <service endpoint URL>/rest/<version> is referred as <base URL>.

All parts of URL to the right of hostname are case-sensitive.

Depending on Accept header in HTTP request (Accept: application/json, Accept: text/xml or Accept: application/xml), information in the response rendered in either JSON or XML format. If not specified it defaults to text/html and output is compatible with ordinary web browser.

In the HTTP response headers the HTTP Status-Code (RFC7231) indicates the status of the overal request (e.g. 403 corresponds to the forbidden).

For the operations that support multiple (bulk) requests per single API call, in addition to the Status-Code in HTTP header, the per-request Status-Codes are returned. They are included as a part of the response array in HTTP body using the same RFC2731 values following the syntax defined below.

Description of functionalities and operations

Requesting supported versions

GET <service endpoint URL>/rest

Operations:

GET - returns list of supported REST API versions

POST, PUT, DELETE - not supported

Example response:

The XML response is like:

<versions>
  <version>1.0</version>
  <version>1.1</version>
  <version>1.2</version>
</versions>

The JSON is:

{version: [ "1.0", "1.1", "1.2" ]}

or

{version: "1.0"}

Obtaining CE resource information

GET <base URL>/info[?schema=glue2]

Operations:

GET - retrieve generic information about cluster properties. It accepts the optional schema parameter. The default and only supported value in the currect ARC release is glue2. The CRR rendering might be added in the future ARC releases. XML or JSON returned according to request headers.

HEAD - supported

PUT, POST, DELETE - not supported.

Example QUERY:

GET https://host.domain.org:443/arex/rest/1.0/info?schema=glue2 HTTP/1.1
Accept: application/xml

The XML response is:

<InfoRoot>
  <Domains xmlns="http://schemas.ogf.org/glue/2009/03/spec_2.0_r1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="https://raw.github.com/OGF-GLUE/XSD/master/schema/GLUE2.xsd">
    <AdminDomain BaseType="Domain" CreationTime="2018-11-06T20:26:46Z" Validity="10800">
      <ID>urn:ad:UNDEFINEDVALUE</ID>
      <Name>UNDEFINEDVALUE</Name>
      <Distributed>false</Distributed>
      <Services>
        <ComputingService BaseType="Service" CreationTime="2018-11-06T20:26:46Z" Validity="10800">
          <ID>urn:ogf:ComputingService:arc.zero:arex</ID>
          <Capability>data.transfer.cepush.srm</Capability>
          <Capability>executionmanagement.jobmanager</Capability>
 ... output omitted ...

Operating jobs

GET <base URL>/jobs[?state=<state1>[,<state2>[…]]]

POST <base URL>/jobs?action=new[&queue=<name>][&delegation_id=<id>]

POST <base URL>/jobs?action={info|status|kill|clean|restart|delegations}

Operations:

GET - get list of jobs

HEAD - supported

POST - job submission and management

PUT, DELETE - not supported

Get list of jobs

GET <base URL>/jobs retrieves list of jobs belonging to authenticated user as application/xml or application/json. Returned document contains list of job IDs.

It accepts the optional state parameters. When defined the returned document contains only jobs in the requested state(s).

Example QUERY:

GET https://host.domain.org:443/arex/rest/1.0/jobs HTTP/1.1
Accept: application/xml

The XML response is:

<jobs>
  <job>
    <id>1234567890abcdef</id>
  </job>
  <job>
    <id>fedcba0987654321</id>
  </job>
</jobs>

The JSON is:

{
  "job":[
    {"id":"1234567890abcdef"},
    {"id":"fedcba0987654321"}
  ]
}

Job submission (create a new job)

POST <base URL>/jobs?action=new initiates creation of a new job instance or multiple jobs.

Request body contains job description(s), in one of the supported formats: ADL as Content-type: application/xml or xRSL as Content-type: applicaton/rsl.

The optional queue parameter defines the default value for the computing element queue. The value has same effect as xRLS xrsl_queue (or ADL QueueName) and applied to all job descriptions that does not have it specified. If xRSL/ADL already contains queue the value from xRLS/ADL is used instaed.

The optional delegation_id parameter defines the default value for the delegation ID for data staging. The value has same effect as xRLS xrsl_delagationid (or ADL DelegationID) and applied to all job descriptions that does not have it specified. If xRSL/ADL already contains delegationid the value from xRLS/ADL is used instaed.

To pass multiple job descriptions in document body of the same type:

ADL descriptions are enclosed in <ActivityDescriptions> element

XRSL uses + to merge multiple jobs.

Response contains 201 code. Response body contains an array of elements corresponding to the sequence of the job descriptions in the requests in the same order. The elemenets of the array in the response contains:

status-code: a 3-digit integer result code of the attempt to understand and satisfy the request (according to RFC7231)

reason: a short textual description of the Status-Code

id: job UUID or None if not assigned (non-successfull submission)

state: the job state according to state model or None if not available (non-successfull submission)
The XML response is:
<jobs>
  <job>
    <status-code>201</status-code>
    <reason>Created</reason>
    <id>1234567890abcdef</id>
    <state>ACCEPTING</state>
  </job>
  <job>
    <status-code>500</status-code>
    <reason>Requested RTE is missing</reason>
  </job>
</jobs>
The JSON is:
{
  "job":[
    {
      "status-code":"201",
      "reason":"Created",
      "id":"1234567890abcdef",
      "state":"ACCEPTING"
    },
    {
      "status-code":"500",
      "reason":"Requested RTE is missing",
    }
  ]
}

Jobs management

POST <base URL>/jobs?action={info|status|kill|clean|restart|delegations} - job management operations supporting arrays of jobs.

Request body contains list of jobids as JSON/XML (e.g. output of GET <base URL>/jobs can be reused).

Example of the body in XML:

<jobs>
  <job>
    <id>1234567890abcdef</id>
  </job>
  <job>
    <id>fedcba0987654321</id>
  </job>
</jobs>

And in JSON:

{
  "job":[
    {"id":"1234567890abcdef"},
    {"id":"fedcba0987654321"}
  ]
}

Response depends on the requested action:

Job info: POST <base URL>/jobs?action=info retrieves full information about job(s) according to the GLUE2 activity information XML document, or in JSON format.

Response contains 201 code. Response body contains an array of elements corresponding to the job IDs in the requests. The elemenets of the array in the response contains:

status-code: a 3-digit integer result code of the attempt to understand and satisfy the request (according to RFC7231). The 200 is only positive response.

reason: a short textual description of the Status-Code

id: job UUID

info_document: GLUE2 activity information about the job or empty documents if not available (request if not satisfiable)

Job status: POST <base URL>/jobs?action=status retrieves information about job(s) current state.