.. _query_api: How to query the API ? ====================== If this Goslin REST API can be queried directly from the MetaboCloud website (See :ref:`web_usage`), it can also be queried programmatically. With cURL --------- The REST API is queryable in command line by using ``cURL`` .. tabs:: .. tab:: One lipid name | *Example of a query with only one lipid name :* ``Cer 18:1;2/16:0`` | **Command :** .. code-block:: curl -i --url 'https://metabocloud.mesocentre.uca.fr/goslin/validate?lipid_names=Cer%2018%3A1%3B2%2F16%3A0' | **Output :** .. code-block:: console 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"}]} .. tab:: Several lipid names | *Example of a query with several lipid names :* ``Cer 18:1;2/16:0``, ``PC (4a:0)``, ``Vitamin D5`` | **Command :** .. code-block:: curl -i --url 'https://metabocloud.mesocentre.uca.fr/goslin/validate?lipid_names=Cer%2018%3A1%3B2%2F16%3A0&lipid_names=PC%20%284a%3A0%29&lipid_names=Vitamin%20D5' | **Output :** .. code-block:: console HTTP/2 200 access-control-allow-origin: * access-control-expose-headers: * content-type: application/json date: Thu, 17 Apr 2025 14:18:49 GMT server: WSGIServer/0.2 CPython/3.10.16 content-length: 1035 {"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"}]} With Python ----------- One of the ways to query a REST API with Python is to use the `requests`_ library. .. _requests: https://fr.python-requests.org/en/latest/ 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", ...]): .. code-block:: python 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 : .. code-block:: python print(json_output) .. code-block:: json { "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 : .. code-block:: python 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"]) .. code-block:: console 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 .. _Swagger: https://editor.swagger.io/