Interact with the Process API

This API aims to programmatically list, launch and monitor EDITO processes and is in the way to being 100% compliant with the OGC API Processes standard.

Context: You can interact with the Process API from any terminal that has network access to https://api.dive.edito.eu. Make sure you have set up your access token if the endpoint requires authentication

Vocabulary

Process: In the context of this API, a process is the definition of a computation.
Job: The request for the execution of a process results in the creation of a Job.

Retrieve the list of processes

This endpoint does not require authentication, so you won’t need a token to call it.

curl https://api.dive.edito.eu/processes/processes

Tip: You can run this command in your terminal (local machine or container terminal). It will return the full list of processes available on the platform. Each element contains a summary and a unique id key identifying the process.

Retrieve one process

This endpoint is authenticated, so you will need a token to call it. See the Get tokens and access tokens article. You need to set the client_id to onyxia.

For this example, let’s say you know that the id of the process you’re interested in is the following: process-playground-coral-bleaching-detection-0.1.18. Here is the curl command to retrieve the detail of this process:

curl https://api.dive.edito.eu/processes/processes/process-playground-coral-bleaching-detection-0.1.18

The response is a json containing the same informations provided by the /processes endpoint, along with 2 additionnal keys:

inputs: A JSON schema that describes what must be the inputs you we’ll have to send if you want to execute (or trigger, or run…) this process.
outputs: A JSON schema that represents the JSON that will be returned by the /jobs/<my-job-id>/results endpoint once an instance of this process (a job) has finished.

Execute a process

This endpoint is authenticated, so you will need a token to call it. See the Get tokens and access tokens article. You need to set the client_id to onyxia.

To trigger a process job, you need to send a HTTP POST request along with a JSON body. This body needs to conforms to the JSON schema defined by the inputs section of the process description

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" -d @payload.json https://api.dive.edito.eu/processes/processes/process-playground-coral-bleaching-detection-0.1.18/execution

With the following body payload.json:

{
    "metadata": {
        "project": "user-available-project"  // You need to specify a group project you belongs to if you want to execute the process within a group project. On the other hand, if you want execute the process in your personal project, then remove this line.
    },
    "processInputs": {
        "copernicusCredentials": {
            "password": "copernicusMarinePassword",
            "username": "copernicusMarineUsername"
        },
        "demo": {
            "smallDemo": true
        },
        "onyxia": {
            "friendlyName": "coral-bleaching-detection",
            "share": false
        },
        "resources": {
            "limits": {
                "cpu": "500m",
                "memory": "2Gi"
            },
            "requests": {
                "cpu": "100m",
                "memory": "1Gi"
            }
        },
        "s3": {
            "accessKeyId": "S3AccessKeyId",
            "defaultRegion": "s3Region",
            "enabled": true,
            "endpoint": "s3.endpoint",
            "secretAccessKey": "S3AccessKey",
            "sessionToken": "S3SessionToken"
        }
    }
}

If everything went well, the API will return you a 201 CREATED HTTP response. The header of the response return the HTTP Location header that contains a link to the newly created job so that you can monitor it!

Monitor your Job

This endpoint is authenticated, so you will need a token to call it. See the Get tokens and access tokens article. You need to set the client_id to onyxia.

Once your Job is running, you can use the following command to monitor it by using the URL provided by the HTTP Location response header (see the Execute a process section)

curl -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" https://api.dive.edito.eu/processes/jobs/coral-bleaching-detection-302899

Retrieve your Job’s results

This endpoint is authenticated, so you will need a token to call it. See the Get tokens and access tokens article. You need to set the client_id to onyxia.

Once your Job has ended, the results are available using the following command:

curl -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" https://api.dive.edito.eu/processes/jobs/coral-bleaching-detection-302899/results

The results (or outputs) must match the JSON schema provided by the outputs key of the process description (see the Retrieve one process section).