|
|
# Features to have:
|
|
|
|
|
|
1. Effective bulk operations: with http v2, will require httpv2 development for HED, this feature can be postponed
|
|
|
2. Support for versioning: via url paths like https://arc.zero:443/arex/rest/1.0/jobs
|
|
|
3. Usable with simple tools (wget, curl)
|
|
|
4. Accessible through Web Browser: not the most important
|
|
|
5. Friendly to common HTTP REST frameworks
|
|
|
6. Interactive support to session directory (with proper protection and WebDAV basic support later)
|
|
|
7. Machine readable error/result codes/messages
|
|
|
8. Re-use of existing software modules (no drastic changes to information representation and jobs handling)
|
|
|
9. support different response formats: html, xml, json
|
|
|
|
|
|
|
|
|
# Description of supported operations.
|
|
|
|
|
|
## URL path
|
|
|
The various functionalities of the service are accessible through HTTP(S) URL built upon following pattern:
|
|
|
\<service endpoint URL\>/rest/\<version\>/\<functionality\>
|
|
|
|
|
|
Here \<service endpoint URL\> represents mounting point of the service and may look like https://host.domain.org:443/arex .
|
|
|
The \<version\> is two parts number separated by '.'. Current version is "1.0".
|
|
|
The \<functionality\> is one of keywords defined below.
|
|
|
|
|
|
Further the part \<service endpoint URL\>/rest/\<version\> is referred as \<base\>.
|
|
|
|
|
|
All parts of URL are case-sensitive.
|
|
|
|
|
|
GET with "Accept: text/html" on each resource returns HTML with some useful information for web browser compatibility.
|
|
|
|
|
|
GET on \<service endpoint URL\>/rest returns list of supported versions. The XML response is like:
|
|
|
<pre>
|
|
|
<versions>
|
|
|
<version>0.1</version>
|
|
|
<version>0.2</version>
|
|
|
<version>0.3</version>
|
|
|
</versions>
|
|
|
</pre>
|
|
|
The JSON is:
|
|
|
<pre>
|
|
|
{
|
|
|
"version":"0.1",
|
|
|
"version":"0.2",
|
|
|
"version":"0.3"
|
|
|
}
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
## Functionality as resource.
|
|
|
Access to general functionality of the CE through URL.
|
|
|
\<base URL\>
|
|
|
Operations:
|
|
|
- GET - retrieve generic information about cluster (consider filtering through URL options), maybe shall include references (relative URLs) to underlying resources. The information is GLUE2 XML document. For JSON response it is automatically converted into JSON with top node removed and attributes ignored.
|
|
|
- HEAD - supported.
|
|
|
- PUT,POST,DELETE - not supported.
|
|
|
|
|
|
|
|
|
## Delegation functionality.
|
|
|
\<base URL\>/delegations
|
|
|
Operations:
|
|
|
- GET - retrieves list of delegations belonging to authenticated user (consider paging through URL options). The XML response is:
|
|
|
<pre>
|
|
|
<delegations>
|
|
|
<delegation>
|
|
|
<id>1234567890abcdef</id>
|
|
|
</delegation>
|
|
|
<delegation>
|
|
|
<id>fedcba0987654321</id>
|
|
|
</delegation>
|
|
|
</delegations>
|
|
|
</pre>
|
|
|
The JSON is:
|
|
|
<pre>
|
|
|
{
|
|
|
"delegation":{
|
|
|
"id":"1234567890abcdef"
|
|
|
},
|
|
|
"delegation":{
|
|
|
"id":"fedcba0987654321"
|
|
|
}
|
|
|
}
|
|
|
</pre>
|
|
|
- HEAD - supported.
|
|
|
- PUT - not supported.
|
|
|
- POST - initiates delegation, no options or body expected. This is a 2 step process. Step 1 generates pair of private/public keys on server side and communicates X.509 certificate request to the client. Response is 201 and contains certificate request of application/x-pem-file type and URL of delegation in Location header with assigned delegation id.
|
|
|
- DELETE - not supported.
|
|
|
|
|
|
|
|
|
## Delegation as resource
|
|
|
\<base URL\>/delegations/\<delegation id\> - only available to owner of delegation
|
|
|
Operations:
|
|
|
- GET - returns public part of the stored delegation as application/x-pem-file.
|
|
|
- HEAD - supported.
|
|
|
- PUT - stores public part of delegated certificate to finish delegation procedure (2nd step of delegation procedure) or to re-new delegation without changing private key.
|
|
|
- POST - initiates renewal of delegation under same delegation id. No options or body expected. Response is 200 with certificate request of application/x-pem-file type.
|
|
|
- DELETE - removes delegation.
|
|
|
|
|
|
|
|
|
## Job control functionality
|
|
|
\<base URL\>/jobs
|
|
|
Operations:
|
|
|
- GET - retrieves list of jobs belonging to authenticated user (consider paging and filtering through URL options) as text/html, application/xml or application/json. Returned document contains minimal information about job - currebtly only job identifier. TODO: consider providing list of all jobs (or per-VO jobs) to special user identity (for monitoring). The XML response is (subject to change, maybe it would be better to use GLUE2 elements):
|
|
|
<pre>
|
|
|
<jobs>
|
|
|
<job>
|
|
|
<id>1234567890abcdef</id>
|
|
|
</job>
|
|
|
<job>
|
|
|
<id>fedcba0987654321</id>
|
|
|
</job>
|
|
|
</jobs>
|
|
|
</pre>
|
|
|
The JSON is:
|
|
|
<pre>
|
|
|
{
|
|
|
"job":{
|
|
|
"id":"1234567890abcdef"
|
|
|
},
|
|
|
"job":{
|
|
|
"id":"fedcba0987654321"
|
|
|
}
|
|
|
}
|
|
|
</pre>
|
|
|
|
|
|
- HEAD - supported.
|
|
|
- PUT - not supported.
|
|
|
- POST - initiates new job. Without URL options body contains job description in whatever format is supported (currently EMI-ES as application/xml and XRSL as applicaton/rsl). Response is 201 with Location header referring to created job resource and body contains minimal information about job (not implemented yet, must define which elements must be present).
|
|
|
- DELETE - not supported
|
|
|
|
|
|
|
|
|
## Job as resource.
|
|
|
Each job is represented by URL
|
|
|
\<base URL\>/jobs/\<job id\>
|
|
|
Operations:
|
|
|
- GET - Retrieves full information about job (famous GLUE2 XML file, automatically converted to JSON).
|
|
|
- HEAD - supported.
|
|
|
- DELETE - initiates clear request for the job.
|
|
|
- POST - accepts requests to modify job. Currently cancel and restart through passing partial job information (XML or JSON (to be implemented)) with requested job state in HTTP body. Currently accepted states are emies:terminal for canceling job and emies:accepted for restarting. Example of request:
|
|
|
<pre>
|
|
|
<ComputingActivity>
|
|
|
<State>emies:terminal<State>
|
|
|
</ComputingActivity>
|
|
|
</pre>
|
|
|
The response code is 202 to indicate request is queued for later execution.
|
|
|
|
|
|
## Sub-resources of the job.
|
|
|
### Session directory
|
|
|
\<base URL\>/jobs/\<job id\>/session/...
|
|
|
Operations:
|
|
|
- GET,HEAD,PUT,DELETE - supported for files stored in job's session directory and perform usual actions.
|
|
|
- GET,HEAD - for directories retrieves list of stored files (consider WebDAV for format).
|
|
|
- DELETE - for directories removes whole directory.
|
|
|
- PUT - for directory not supported.
|
|
|
- POST - not supported.
|
|
|
- PATCH - for files modifies part of files (body format need to be defined, all files treated as binary, currently support non-standard PUT with ranges).
|
|
|
|
|
|
|
|
|
### Information about job.
|
|
|
\<base URL\>/jobs/\<job id\>/\<information type\>
|
|
|
For \<information type\> just follow controldir layout.
|
|
|
Operations:
|
|
|
- GET - retrieves content of corresponding controldir file with type text/plain or application/xml according to file type.
|
|
|
- HEAD - supported.
|
|
|
- PUT, POST, DELETE - not supported.
|
|
|
|
|
|
|
|
|
### Information about job's delegations.
|
|
|
\<base URL\>/jobs/\<job id\>/delegations
|
|
|
\<base URL\>/jobs/\<job id\>/delegations/\<delegation id\>
|
|
|
Provides read-only access to delegations associated with the job identically to <base URL>/delegations (only GET,HEAD methods supported)
|
|
|
|
|
|
|
|
|
This page has moved to https://source.coderefinery.org/nordugrid/doc/blob/master/source/tech/rest/rest.rst |
|
|
\ No newline at end of file |