# 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: Method: /porch/ or /info/ (or / if no authentication credentials are provided) GET (none) 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. 200 - OK & CLAM XML

## Project Index¶

Endpoint: Method: /index/ (or / if proper authentication credentials are provided) GET (none) Retrieves the project index and general webservice specification 200 - OK & CLAM XML, 401 - Unauthorised

## Project Endpoint¶

Endpoint: Method: /[project]/ GET (none) 200 - OK & CLAM XML, 401 - Unauthorised, 404 - Not Found 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. PUT (none) 201 - Created, 401 - Unauthorised, 403 - Forbidden (Invalid project ID), 403 - Forbidden (No project name) This is necessary before attempting to upload any files; it initialises an empty new project. POST 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 202 - Accepted & CLAM XML, 401 - Unauthorised, 404 - Not Found, 403 - Permission Denied & CLAM XML, 500 - Internal Server Error 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. DELETE The parameter abortonly can be set to 1 if you only want to abort a running process without deleting the entire project 200 - OK, 401 - Unauthorised, 404 - Not Found Deletes a project. Any running processes will be aborted.

## Input files¶

Endpoint: Method: /[project]/input/[filename] GET (none) 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found Retrieves the specified input file. DELETE (none) 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found Deletes the specified input file. /[project]/input/[filename] or /[project]/input/[inputtemplate]/[filename] POST 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. 200 - OK & CLAM-Upload XML, 403 - Permission Denied & CLAM-Upload XML, 401 - Unauthorised, 404 - Not Found 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. /[project]/input/[filename]/metadata GET (none) 200 - OK & CLAM Metadata XML, 401 - Unauthorised, 404 - Not Found Retrieves the metadata for the specified input file.

## Output Files¶

Endpoint: Method: /[project]/output/[filename] GET (none) 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found Retrieves the specified output file. DELETE (none) 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found Deletes the specified output file. PUT (none) 200 - OK & JSON reply with field url indicating where the file can be downloaded (one time only) publicly, 401 - Unauthorised, 404 - Not Found 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). /[project]/output/[filename]/metadata GET (none) 200 - OK & CLAM Metadata XML, 401 - Unauthorised, 404 - Not Found Retrieves the metadata for the specified output file.

Endpoint: Method: /[project]/output/ GET format=zip|tar.gz|tar.bz2 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found Offers a single archive, of the desired format, including all output files DELETE (none) 200 - OK & File contents, 401 - Unauthorised Deletes all output files and resets the project for another run.

## Temporary Storage¶

Endpoint: Method: /storage/[id] GET keep (optional) - Set to 1 to preserve the link for another use after download. 200 - OK & File contents, 401 - Unauthorised, 404 - Not Found 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: Method: /actions/[action_id]/ GET and/or POST, may be constrained by the action Determined by the action 200 - OK & Result data determined by the action, 401 - Unauthorised, 404 - Not Found 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 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}_). 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.