... | ... | @@ -11,111 +11,97 @@ |
|
|
9. support different response formats: html, xml and later json
|
|
|
|
|
|
|
|
|
# Design basics.
|
|
|
|
|
|
## Functionality as resource.
|
|
|
Access to general functionality of the CE through URL :
|
|
|
<base URL>/cluster
|
|
|
Operations:
|
|
|
- retrieve generic information about cluster (GET command)
|
|
|
|
|
|
## Delegation functionality:
|
|
|
<base URL>/delegation
|
|
|
- Initiate delegation, perform delegation (POST or GET/PUT combination)
|
|
|
|
|
|
## Delegation as resource
|
|
|
<base URL>/delegation/<delegation id>
|
|
|
- Update delegation (method?)
|
|
|
|
|
|
## Job control functionality:
|
|
|
<base URL>/jobs
|
|
|
- Initiate new job(s) (POST, should PUT into subdir also create new job?)
|
|
|
|
|
|
## Job as resource. Each job is represented by URL
|
|
|
<base URL>/jobs/<job id>
|
|
|
- Modify job - cancel, pause, resume (POST, similar to new job creation?)
|
|
|
- Clean job (DELETE)
|
|
|
|
|
|
## Sub-resources of the job.
|
|
|
### Session directory:
|
|
|
<base URL>/jobs/<job id>/session
|
|
|
- store, modify, retrieve files in session directory (PUT, GET, DELETE, maybe use POST for altering part of the file?)
|
|
|
|
|
|
### Information about job:
|
|
|
<base URL>/jobs/<job id>/info/<information type>
|
|
|
- just follow controldir layout
|
|
|
- read-only.
|
|
|
|
|
|
Information about all jobs of a cluster (for a job monitor):
|
|
|
TO BE DISCUSSED
|
|
|
|
|
|
## Web browser compatibility
|
|
|
GET with "Accept: text/html" on each resource returns HTML with some useful information.
|
|
|
|
|
|
|
|
|
# Technical description of supported operations
|
|
|
# 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>/<version>/<functionality>
|
|
|
<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 <version> is two parts number separated by '.' prefixed with 'v;. Current version is "v1.0".
|
|
|
The <functionality> is one of keywords defined below.
|
|
|
|
|
|
Further the part <service endpoint URL/<version> is referred as <base>.
|
|
|
|
|
|
|
|
|
## Definitions of job control operations
|
|
|
|
|
|
<functionality> = jobs
|
|
|
|
|
|
### Submit job
|
|
|
|
|
|
### Cancel job
|
|
|
|
|
|
### Pause job
|
|
|
|
|
|
### Resume job
|
|
|
|
|
|
### Restart job
|
|
|
Further the part <service endpoint URL>/rest/<version> is referred as <base>.
|
|
|
|
|
|
### Delete job
|
|
|
All parts of URL are case-sensitive.
|
|
|
|
|
|
### Access job information
|
|
|
GET with "Accept: text/html" on each resource returns HTML with some useful information for web browser compatibility.
|
|
|
|
|
|
## Definitions of job data access operations
|
|
|
Consider GET on <service endpoint URL>/rest return list of supported versions?
|
|
|
|
|
|
### Store file
|
|
|
<base URL>/jobs/<job id>/session
|
|
|
|
|
|
### Read file
|
|
|
|
|
|
### Modify file
|
|
|
## 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.
|
|
|
- HEAD - supported.
|
|
|
- PUT,POST,DELETE - not supported.
|
|
|
|
|
|
## Definition of delegation operation
|
|
|
|
|
|
<functionality> = delegation
|
|
|
## Delegation functionality.
|
|
|
<base URL>/delegations
|
|
|
Operations:
|
|
|
- GET - retrieves list of delegations belonging to authenticated user (consider paging through URL options) as text/html, application/xml or application/json.
|
|
|
- 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 - removes all delegations belonging to authenticated user.
|
|
|
|
|
|
### Create new delegation
|
|
|
|
|
|
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. It is initiated by HTTP GET request:
|
|
|
## 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 or to re-new delegation.
|
|
|
- POST - initiates renewal of delegation under same delegation id. No options or bode expected. Response is 200 with certificate request of application/x-pem-file type.
|
|
|
- DELETE - removes delegation.
|
|
|
|
|
|
GET <base>/delegation HTTP/X.X
|
|
|
|
|
|
And response is HTTP 200 reponse with X.509 certificate request as body:
|
|
|
## 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 - probably job state, references to selected sub-resources of the job. Also consider providing list of all jobs (or per-VO jobs) to special user identity (for monitoring).
|
|
|
- HEAD - supported.
|
|
|
- PUT - not supported.
|
|
|
- POST - initiates new job. Without URL options body contains job description in whatever format is supported (currently probably application/xml or applicaton/rsl). Response is 201 with Location header referring to created job resource and body contains minimal information about job.
|
|
|
- DELETE - initiates clear request for all jobs belonging to authenticated user.
|
|
|
|
|
|
HTTP/X.X 200 <delegation id>
|
|
|
Content-Type: application/x-pem-file
|
|
|
Content-Length: XXXX
|
|
|
Connection: close
|
|
|
|
|
|
-----BEGIN CERTIFICATE REQUEST-----
|
|
|
...
|
|
|
-----END CERTIFICATE REQUEST-----
|
|
|
## Job as resource. Each job is represented by URL
|
|
|
<base URL>/jobs/<job id>
|
|
|
Operations:
|
|
|
- GET - Retrieves full information about job (famous XML file, possibly 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 in body partial job information with requested job state.
|
|
|
|
|
|
|
|
|
### Update existing delegation
|
|
|
## 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)
|
|
|
|
|
|
### Access delegation metadata
|
|
|
|