How to query the API ?

If this Goslin REST API can be queried directly from the MetaboCloud website (See Web usage), it can also be queried programmatically.

With cURL

The REST API is queryable in command line by using cURL

Example of a query with only one lipid name : Cer 18:1;2/16:0
Command :
curl -i --url 'https://metabocloud.mesocentre.uca.fr/goslin/validate?lipid_names=Cer%2018%3A1%3B2%2F16%3A0'
Output :
HTTP/2 200
access-control-allow-origin: *
access-control-expose-headers: *
content-type: application/json
date: Thu, 17 Apr 2025 14:07:37 GMT
server: WSGIServer/0.2 CPython/3.10.16
content-length: 2369

{"nb_total_lipids":1,"nb_success":1,"nb_total_not_parsed":0,"nb_not_parsed_uncompleted":0,"nb_not_parsed_failures":0,"lipid_list":[{"state":"Success","normalized_name":"Cer 18:1;O2/16:0","original_name":"Cer 18:1;2/16:0","grammar":"Goslin","lipidmaps_category":"SP","lipidmaps_class":"Ceramides [SP02]","class_name":"Cer","extended_class":"Cer","lipid_level":"SN_POSITION","lipidmaps_data":{"LMSP02010004":{"inchi_key":"YDNKGFDKKRUKPY-TURZORIXSA-N","swisslipids_id":"SLM:000000554"},"LMSP02010036":{"inchi_key":"DLTXHYMYPKOZOA-TURZORIXSA-N","swisslipids_id":"SLM:000397291"},"LMSP02010046":{"inchi_key":"UQKAUNJILIUTGT-TURZORIXSA-N","swisslipids_id":"SLM:000397537"}},"mass":537.5120952350001,"formula":"C34H67NO3"}]}

With Python

One of the ways to query a REST API with Python is to use the requests library.

After installing the requests library, you can query the Goslin REST-API with the following statements by defining the lipid names you want to standardize as a list as a value of the lipid_names key of the params option dictionary (e.g. {“lipid_names” : [“name1”, “name2”, …]):

import requests

result = requests.get(f"https://metabocloud.mesocentre.uca.fr/goslin/validate", verify=False, params={"lipid_names" : ["Cer 18:1;2/16:0", "PC (4a:0)", "Vitamin D5"]})

json_output = result.json()

Note

If you ran the Goslin application locally on your machine from a virtual environment or via Docker, you need to change the URL you send the request to. This means that https://metabocloud.mesocentre.uca.fr/goslin/validate will become http://localhost:8080/validate if you launched the application with the default parameters.

If you choose another port to run the application then you need to change the URL accordingly.

You can therefore retrieve the entire output return by the API in JSON format :

print(json_output)

{
  "nb_total_lipids": 3,
  "nb_success": 1,
  "nb_total_not_parsed": 2,
  "nb_not_parsed_uncompleted": 1,
  "nb_not_parsed_failures": 1,
  "lipid_list": [
    {
      "state": "Success",
      "normalized_name": "Cer 18:1;O2/16:0",
      "original_name": "Cer 18:1;2/16:0",
      "grammar": "Goslin",
      "lipidmaps_category": "SP",
      "lipidmaps_class": "Ceramides [SP02]",
      "class_name": "Cer",
      "extended_class": "Cer",
      "lipid_level": "SN_POSITION",
      "lipidmaps_data": {
        "LMSP02010004": {
          "inchi_key": "YDNKGFDKKRUKPY-TURZORIXSA-N",
          "swisslipids_id": "SLM:000000554"
        },
        "LMSP02010036": {
          "inchi_key": "DLTXHYMYPKOZOA-TURZORIXSA-N",
          "swisslipids_id": "SLM:000397291"
        },
        "LMSP02010046": {
          "inchi_key": "UQKAUNJILIUTGT-TURZORIXSA-N",
          "swisslipids_id": "SLM:000397537"
        }
      },
      "mass": 537.5120952350001,
      "formula": "C34H67NO3"
    },
    {
      "state": "Uncompleted",
      "original_name": "PC (4a:0)",
      "messages": {
        "Shorthand2020": "PC",
        "Goslin": "PC",
        "FattyAcids": "",
        "LipidMaps": "PC ",
        "SwissLipids": "PC",
        "HMDB": "PC"
      }
    },
    {
      "state": "Failure",
      "original_name": "Vitamin D5",
      "messages": "Lipid not found"
    }
  ]
}

Or only the part that interests you :

print("Total number of lipids parsed : ", json_output["nb_total_lipids"])
print("Total number of lipids parsed successfully : ", json_output["nb_success"])
print("Total number of lipids parsed unsuccessfully : ", json_output["nb_total_not_parsed"])

print("List of the lipids parsed : ", json_output["lipid_list"])

Total number of lipids parsed :  3
Total number of lipids parsed successfully :  1
Total number of lipids parsed unsuccessfully :  2
List of the lipids parsed :  [{"state":"Success","normalized_name":"Cer 18:1;O2/16:0","original_name":"Cer 18:1;2/16:0","grammar":"Goslin","lipidmaps_category":"SP","lipidmaps_class":"Ceramides [SP02]","class_name":"Cer","extended_class":"Cer","lipid_level":"SN_POSITION","lipidmaps_data":{"LMSP02010004":{"inchi_key":"YDNKGFDKKRUKPY-TURZORIXSA-N","swisslipids_id":"SLM:000000554"},"LMSP02010036":{"inchi_key":"DLTXHYMYPKOZOA-TURZORIXSA-N","swisslipids_id":"SLM:000397291"},"LMSP02010046":{"inchi_key":"UQKAUNJILIUTGT-TURZORIXSA-N","swisslipids_id":"SLM:000397537"}},"mass":537.5120952350001,"formula":"C34H67NO3"},{"state":"Uncompleted","original_name":"PC (4a:0)","messages":{"Shorthand2020":"PC","Goslin":"PC","FattyAcids":"","LipidMaps":"PC ","SwissLipids":"PC","HMDB":"PC"}},{"state":"Failure","original_name":"Vitamin D5","messages":"Lipid not found"}]

With a client generated by Swagger

From the OpenAPI specification file describing this REST API, you can auto-generated a client in the language you want thanks to Swagger using the option Generate Client in the menu.

The OpenAPI specification file is downloadable here : https://metabocloud.mesocentre.uca.fr/goslin/metabocloud-goslin.yaml