Interact with the Service API

Every services on the EDITO datalab can be programmatically configured and launched using an API. You can find the list of the available endpoints on the swagger page.

List available services

You can list the availables services sorted by catalog with the following request:

curl -X "GET"  -H "accept: */*" "https://datalab.dive.edito.eu/api/public/catalogs"

Tip: Run this command in your terminal. It returns a list of catalogs. Each catalog contains multiple service entries along with their configuration options. You will use this information to populate your payload when launching a service.

Launch a service

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.

In this example, we will launch the Jupyter python ocean science service.

For launching a service, everything will happen in the payload. Simply run:

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" -d @payload.json https://datalab.dive.edito.eu/api/my-lab/app

Where payload.json is:

{
  "catalogId": "ocean-modelling",
  "packageName": "jupyter-python-ocean-science",
  "packageVersion": "1.0.2",
  "name": "jupyter-python-ocean-science-api",
  "options": {
    "ingress": {
      "enabled": true,
      "hostname": "custom-ingress.lab.dive.edito.eu",
      "ingressClassName": "",
      "userHostname": "custom-ingress-user.lab.dive.edito.eu"
    },
    "onyxia": {
      "friendlyName": "jupyter-python-ocean-science",
      "owner": "YOUR_USERNAME", # Don't forget to change this field
      "share": false,
      "userDefinedValues": ""
    },
    "persistence": { "enabled": true, "size": "10Gi" },
    "repository": { "condaRepository": "", "pipRepository": "" },
    "resources": {
      "limits": { "cpu": "3000m", "memory": "8Gi" },
      "requests": { "cpu": "100m", "memory": "2Gi" }
    },
    "security": {
      "allowlist": { "enabled": false, "ip": "10.100.109.194" },
      "networkPolicy": { "enabled": false, "from": [] },
      "password": "CHANGE_ME"
    },
    "catalogType": "Service"
  },
  "dryRun": false
}

The catalogId, packageName, packageVersion and name fields are important to target what service you want to launch and how you want to call it. Please refer to the List available services section to learn what to put in the options field.

Stop a service

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 you are done with your service, you can stop it by calling:

curl -X "DELETE"  -H "accept: */*" -H "Authorization: Bearer {{access_token}}" -H "ONYXIA-PROJECT: YOUR_NAMESPACE" "https://datalab.dive.edito.eu/api/my-lab/app?path=YOUR_SERVICE_ID"

Where YOUR_NAMESPACE is your username prefixed with user- and YOUR_SERVICE_ID is your service id.

Temporarily suspend and resume a service

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.

Some services are build using Kubernetes deployments. This means that you can choose to suspend you service temporarily to save resources. You can do so by calling:

curl -X "POST"  -H "accept: */*" -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" "https://datalab.dive.edito.eu/api/my-lab/app/suspend" -d '{"serviceID": "YOUR_SERVICE_ID"}'

Where YOUR_SERVICE_ID is your service id.

To resume it, simply call:

curl -X "POST"  -H "accept: */*" -H "Content-Type: application/json" -H "Authorization: Bearer {{access_token}}" "https://datalab.dive.edito.eu/api/my-lab/app/resume" -d '{"serviceID": "YOUR_SERVICE_ID"}'