Performing API Operations Using cURL

Applies to PeerGFS v6.1.0 and later

Overview

You can directly access the PeerGFS API using cURL, a versatile command-line tool for making HTTP requests. This article provides guidance on constructing and executing cURL commands to interact with the API. Whether you're running standalone commands or incorporating cURL into custom scripts, these examples will help you effectively utilize the PeerGFS API for automation and integration.

cURL Command Examples

Get Job Status

To retrieve a list of jobs and their status using cURL, run the following command:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/jobs"

This command will return a JSON response with job details, including job IDs, names, statuses, and participant information. You can format the output for better readability by piping the response into a tool like python -m json.tool:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/jobs" | python -m json.tool

Start a Job

To start a job using the API, send a POST request with the job ID. Replace <jobID> with the actual job ID to start:

curl -u admin:password --insecure -X POST "https://<PMC>:8442/api/jobs/start" --data "jobIds=<jobID>"

After sending the request, check the job status again to ensure it has started:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/jobs" | python -m json.tool

Stop a Job

To stop a job, send a POST request with the job ID. Replace <jobID> with the ID of the job you wish to stop:

curl -u admin:password --insecure -X POST "https://<PMC>:8442/api/jobs/stop" --data "jobIds=<jobID>"

After sending the request, verify the job has stopped by fetching the updated status:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/jobs" | python -m json.tool

Retrieve Quarantine Status

To retrieve information about quarantined files, use the following cURL command. This will return a list of quarantined files and their details, including quarantine status and associated job information:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/quarantine"

You can format the output for better readability by piping the response into a tool like python -m json.tool:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/quarantine" | python -m json.tool

Retrieve Quarantine by File ID

If you need more detailed information about a specific quarantined file, you can retrieve its information by using the file’s unique ID:

curl -u admin:password --insecure -X GET "https://<PMC>:8442/api/quarantine/<fileID>"

Replace <fileID> with the ID of the quarantined file you want to query.

Release a File from Quarantine

To release a file from quarantine, send a POST request with the file ID to the appropriate API endpoint. This will remove the file from quarantine and restore it to its previous state:

curl -u admin:password --insecure -X POST "https://<PMC>:8442/api/quarantine/release" --data "fileIds=<fileID>"

Replace <fileID> with the ID of the file you want to release.

Clear All Files from Quarantine

If you need to clear all files from quarantine, you can send a POST request to the following endpoint. This will remove all files from the quarantine:

curl -u admin:password --insecure -X POST "https://<PMC>:8442/api/quarantine/clear"

This command will remove all quarantined files from the system, so be sure to double-check before using it.

Additional Parameters

For POST requests or other operations that require sending data, use the --data or -d flag to include the necessary parameters. For example:

curl -u admin:password --insecure -X POST "https://<PMC>:8442/api/jobs" --data "jobIds=<jobID>"

This approach allows you to integrate API operations into your workflows, making it easier to manage and automate PeerGFS tasks using cURL.