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 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 lipids_names key of the params option dictionnary (e.g. {“lipids_names” : [“name1”, “name2”, …]):

import requests

result = requests.get(f"https://metabocloud.mesocentre.uca.fr/goslin/validate", verify=False, params={"lipids_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_not_parsed": 2,
    "nb_uncompleted": 1,
    "nb_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",
            "mass": 537.5120952350001,
            "sum_formula": "C34H67NO3",
            "lipidsmaps_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"
                }
            }
        },
        {
            "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"
        }
    ],
    "nb_success": 1,
    "nb_total_lipids": 3
}

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_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', 'mass': 537.5120952350001, 'sum_formula': 'C34H67NO3', 'lipidsmaps_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'}}}, {'state': 'Uncompleted', 'original_name': 'PC (4a:0)', 'messages': {'Shorthand2020': 'PC', 'Goslin': 'PC', 'FattyAcids': '', 'LipidMaps': 'PC ', 'SwissLipids': 'PC', 'HMDB': 'PC'}}, {'state': 'Failure', 'original_name': 'cholesterol(d7)', 'messages': 'Lipid not found'}]