RESTful API specification¶
This appendix provides a full specification of the RESTful interface to CLAM.
Note
Note that for each webservice, an auto-generated and human readable RESTful API specification is available at the /info/
endpoint which provides a more tailored overview. This info page also presents auto-generated example code for
interacting with the webservice.
General Webservice Information¶
| Endpoint: | /porch/ or /info/ (or / if no authentication credentials are provided) |
|---|---|
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Description: | Retrieves the general webservice specification (profiles, formats, etc). This also works without
authentication even on authenticated webservices (unless explicitly disabled). /porch/ and /info/
and almost identical from a webservice perspective, but render very differently in the browser. |
| Response: | 200 - OK & CLAM XML |
Project Index¶
| Endpoint: | /index/ (or / if proper authentication credentials are provided) |
|---|---|
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Description: | Retrieves the project index and general webservice specification |
| Response: | 200 - OK & CLAM XML, 401 - Unauthorised |
Project Endpoint¶
| Endpoint: | /[project]/ |
|---|---|
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & CLAM XML, 401 - Unauthorised,
404 - Not Found |
| Description: | This returns the current state of the project in CLAM XML format. Depending on the state this contains a specification of all accepted parameters, all input files, and all output files. Note that errors in parameter validation are encoded in the CLAM XML response; the system will still return a 200 response. |
| Method: | PUT |
| Request Parameters: | |
| (none) | |
| Response: | 201 - Created, 401 - Unauthorised,
403 - Forbidden (Invalid project ID), 403 - Forbidden (No project name) |
| Description: | This is necessary before attempting to upload any files; it initialises an empty new project. |
| Method: | POST |
| Request Parameters: | |
| Accepted parameters are defined in the Service Configuration file (and thus differ per service). The parameter ID corresponds to the parameter keys in the request parameters | |
| Response: | 202 - Accepted & CLAM XML, 401 - Unauthorised,
404 - Not Found, 403 - Permission Denied & CLAM XML,
500 - Internal Server Error |
| Description: | This starts the running of a project, i.e. starts
the actual background program with the specified service-specific
parameters and provided input files. The parameters are provided in
the query string; the input files are provided in separate POST
requests to /[project]/input/[filename], prior to this query. If
any parameter errors occur or no profiles match the input files and
parameters, a 403 response will be returned with errors marked in the
CLAM XML. If a 500 - Server Error is returned, CLAM most likely is
not able to invoke the underlying application or the server has
insufficient free resources. |
| Method: | DELETE |
| Request Parameters: | |
The parameter abortonly can be set to 1
if you only want to abort a running process without deleting the
entire project |
|
| Response: | 200 - OK, 401 - Unauthorised,
404 - Not Found |
| Description: | Deletes a project. Any running processes will be aborted. |
Input files¶
| Endpoint: | /[project]/input/[filename] |
|---|---|
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Retrieves the specified input file. |
| Method: | DELETE |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Deletes the specified input file. |
| Endpoint: | /[project]/input/[filename] or
/[project]/input/[inputtemplate]/[filename] |
| Method: | POST |
| Request Parameters: | |
inputtemplate=[inputtemplate\_id]
file=[HTTP file]* url=[download-url]*
contents=[text-content]* metafile=[HTTP file]
metadata=[CLAM Metadata XML] Other accepted parameters are defined
in the various Input Templates in the Service Configuration file (and
thus differs per service and input template). The parameter ID
corresponds to the parameter keys in the query string. |
|
| Response: | 200 - OK & CLAM-Upload XML, 403 - Permission Denied & CLAM-Upload XML,
401 - Unauthorised, 404 - Not Found |
| Description: | This method adds a new input file, which is
transmitted in the multipart/form-data encoding along with request
parameters and metadata parameters. . The response is returned in
CLAM-Upload XML (distinct from CLAM XML!). Two arguments are
mandatory: the input template, which designates what kind of file will
be added and points to one of the InputTemplate IDs the webservice
supports, and one of the query arguments marked with an asterisk.
Adding a file can proceed either by uploading it from the client
machine (file), by downloading it from another URL (url), or
by passing the contents in the POST message itself (contents).
Only one of these can be used at a time. Metadata can be passed in
three different ways: 1) by simply specifying a metadata field as
request parameters, with the same ID as defined in the input template.
2) setting the metafile attribute to an HTTP file, or 3) by
setting metadata to the full XML string of the metadata
specification. |
| Endpoint: | /[project]/input/[filename]/metadata |
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & CLAM Metadata XML,
401 - Unauthorised, 404 - Not Found |
| Description: | Retrieves the metadata for the specified input file. |
Output Files¶
| Endpoint: | /[project]/output/[filename] |
|---|---|
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Retrieves the specified output file. |
| Method: | DELETE |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Deletes the specified output file. |
| Method: | PUT |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & JSON reply with field url indicating where the file can be downloaded (one time only) publicly, 401 - Unauthorised,
404 - Not Found |
| Description: | Shares the file using unauthenticated temporary storage; returns a JSON response with a URL (key: url). where the file can be downloaded (one time only). The URL contains a random 128-bit ID and is safe as long as it is kept secret (only share over encrypted connections). |
| Endpoint: | /[project]/output/[filename]/metadata |
| Method: | GET |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & CLAM Metadata XML,
401 - Unauthorised, 404 - Not Found |
| Description: | Retrieves the metadata for the specified output file. |
Archive Download¶
| Endpoint: | /[project]/output/ |
|---|---|
| Method: | GET |
| Request Parameters: | |
format=zip|tar.gz|tar.bz2 |
|
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Offers a single archive, of the desired format, including all output files |
| Method: | DELETE |
| Request Parameters: | |
| (none) | |
| Response: | 200 - OK & File contents, 401 - Unauthorised |
| Description: | Deletes all output files and resets the project for another run. |
Temporary Storage¶
| Endpoint: | /storage/[id] |
|---|---|
| Method: | GET |
| Request Parameters: | |
keep (optional) - Set to 1 to preserve the link for another use after download. |
|
| Response: | 200 - OK & File contents, 401 - Unauthorised,
404 - Not Found |
| Description: | Retrieves the specified output file from unauthenticated temporary storage. Files will need to be explicitly made available for this storage (using a PUT request on /[project]/output/[filename]. The download will only work once unless the parameter keep is set to 1. |
Actions¶
| Endpoint: | /actions/[action_id]/ |
|---|---|
| Method: | GET and/or POST, may be constrained by the action |
| Request Parameters: | |
| Determined by the action | |
| Response: | 200 - OK & Result data determined by the action,
401 - Unauthorised, 404 - Not Found |
| Description: | This is a remote procedure call to run the specified action and obtain the results. The parameters are specific to the action. |
Project entry shortcut¶
- This is a shortcut method (available since CLAM v0.99.17) that
- combines the steps of project creation, file adding and upload, in one single GET or POST request. Although more limited than the invididual calls, and less RESTful, it facilitates the job for simpler callers:
| Endpoint: | / |
|---|---|
| Method: | GET or POST |
| Request Parameters: | |
project=[name|new] (mandatory), selects
and if necessary creates the project with the specified name. If the
value is set to new, a random project name will be generated.
{inputtemplate}=[contents] – Pass file contents for the specified
input templateJ (the variable name is the inputtemplate ID), this
corresponds to the contents variable in the non-shortcut method.
{inputtemplate}_url=[url] – Pass a url where to obtain the file
for the specified input templateJ (the variable name contains the
inputtemplate ID), this corresponds to the url variable in the
non-shortcut method. {inputtemplate}_filename=[filename] – Sets
the desired filename for the specified input template, use in
combination with one of the two parameters above. Not needed when the
webservice assigns a fixed filename. start=[0|1] – Set this
parameter to 1 if you want the project to start automatically. The
default is not to start automatically. Other accepted parameters are
defined in the Service Configuration file (and thus differ per
service). For global parameters, the parameter ID corresponds to the
parameter keys in the request parameters, for parameters pertaining to
a specific input template, prepend the ID of the input template and an
underscore to the parameter ID ({inputtemplate}_). |
|
| Response: | 200 - OK & CLAM XML, 401 - Unauthorised,
403 - Permission denied |
If OAuth authentication is enabled and no access token is passed, almost
all URLs return HTTP 303 - See Other and redirect to the
authentication provider. At this stage, user input may be required,
stopping automated clients. After the user input, or if no user input is
required, the authorization provider should relay the user back to a
special CLAM login page with another HTTP 303. This implies the
client should then redo the request with the proper access token. See
the section on OAuth2 authentication for more details.