########
Examples
########

The Goslin API-REST enables to standardize lipid names. Here, you will found some examples of output in JSON format that can be return by the API.
Theses output have been retrieve from requests send to the API via the MetaboCloud website : https://metabocloud.mesocentre.uca.fr/goslin

One lipid name put in the query parameters
==========================================

The API can be used with only one lipid name put as parameters in the query.
In this case, the query will look like : ``https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=yourvalue``

See the :ref:`Web usage section in the Overview <web_usage>` and the :ref:`Swagger documentation <doc_swagger>` for more information about the use
of the API.

When only one valid lipid name is sent with the request, 3 types of output can be returned :

* A **successful** parsing when the API succeeds to parse the lipid name and to provide a standardized name with the information associated.

* An **uncompleted** parsing when the API fails to completely parse the lipid name. This means that at least one of the grammars manage to
  begin reading the lipid name but was not able to provide a standardized name. In this case, a string corresponding to how far a grammar was able 
  to read the lipid name is returned for each grammars used.

* A **failed** parsing when the API was unable to parse the lipid name. The lidip is therefore considered as not found. This may be because the
  lipid name was not valid but also because the lipid name is not part a lipid class supported by pygoslin.

.. tabs::
	.. tab:: Successful parsing
		| *Example of a successful parsing with the lipid name :* ``Cer 18:1;2/16:0``  

		| **Request :**

		.. code-block::
			
			https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Cer%2018%3A1%3B2%2F16%3A0

		| **Output :**

		.. code-block:: json

			{
				"nb_not_parsed": 0,
				"nb_uncompleted": 0,
				"nb_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",
						"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"
							}
						}
					}
				],
				"nb_success": 1,
				"nb_total_lipids": 1
			}

	.. tab:: Uncompleted parsing
		| *Example of an uncompleted parsing with the lipid name :* ``PC (4a:0)``  

		| **Request :**

		.. code-block::
			
			https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=PC%20(4a%3A0)

		| **Output :**

		.. code-block:: json

			{
				"nb_not_parsed": 1,
				"nb_uncompleted": 1,
				"nb_failures": 0,
				"lipid_list": [
					{
						"state": "Uncompleted",
						"original_name": "PC (4a:0)",
						"messages": {
							"Shorthand2020": "PC",
							"Goslin": "PC",
							"FattyAcids": "",
							"LipidMaps": "PC ",
							"SwissLipids": "PC",
							"HMDB": "PC"
						}
					}
				],
				"nb_success": 0,
				"nb_total_lipids": 1
			}

	.. tab:: Failed parsing
		| *Example of a failed parsing with the lipid name :* ``Vitamin D5``  

		| **Request :**

		.. code-block::

			https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Vitamin%20D5
			
		| **Output :**

		.. code-block:: json

			{
				"nb_not_parsed": 1,
				"nb_uncompleted": 0,
				"nb_failures": 1,
				"lipid_list": [
					{
						"state": "Failure",
						"original_name": "Vitamin D5",
						"messages": "Lipid not found"
					}
				],
				"nb_success": 0,
				"nb_total_lipids": 1
			}


Several lipid names put in the query parameters
===============================================

The API can also receive a resquest with several lipid names put as parameters. In this case, the different types of output described above can be
found in the final output of the request. 

.. tabs::

	.. tab:: Example 1
		| *Example of an output for several lipid names given in parameters of the same request :* 
		| ``Cer 18:1;2/16:0, PC (4a:0), Vitamin D5``  

		| **Request :** 
		
		.. code-block::

			https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Cer%2018%3A1%3B2%2F16%3A0&lipids_names=PC%20(4a%3A0)&lipids_names=Vitamin%20D5

		| **Output :**

		.. code-block:: json

			{
				"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
			}

	.. tab:: Example 2
		| *Example of an output for several lipid names given in parameters of the same request :* 
		| ``Cholesterol, LPE O 19:1p, Acetyl acid``  

		| **Request :** 
		
		.. code-block::

			https://metabocloud.mesocentre.uca.fr/goslin/validate?lipids_names=Cholesterol&lipids_names=LPE%20O%2019%3A1p&lipids_names=Acetyl%20acid

		| **Output :**

		.. code-block:: json

			{
				"nb_not_parsed": 1,
				"nb_uncompleted": 1,
				"nb_failures": 0,
				"lipid_list": [
					{
						"state": "Success",
						"normalized_name": "ST 27:1;O",
						"original_name": "Cholesterol",
						"grammar": "Goslin",
						"lipidmaps_category": "ST",
						"lipidmaps_class": "Cholesterol and derivatives [ST0101]",
						"class_name": "Cholesterol",
						"extended_class": "ST 27:1;O",
						"lipid_level": "FULL_STRUCTURE",
						"mass": 386.35486624,
						"sum_formula": "C27H46O",
						"lipidsmaps_data": {
							"LMST01010001": {
								"inchi_key": "HVYWMOMLDIMFJA-DPAQBDIFSA-N",
								"swisslipids_id": "SLM:000000287"
							},
							"LMST01010081": {
								"inchi_key": "HVYWMOMLDIMFJA-VEIPTCAHSA-N",
								"swisslipids_id": null
							},
							"LMST01010089": {
								"inchi_key": "IZVFFXVYBHFIHY-SKCNUYALSA-N",
								"swisslipids_id": "SLM:000000193"
							},
							"LMST01010096": {
								"inchi_key": "QETLKNDKQOXZRP-XTGBIJOFSA-N",
								"swisslipids_id": "SLM:000000468"
							},
							"LMST01010097": {
								"inchi_key": "ONYPIMNXSARKFQ-NFTYELEKSA-N",
								"swisslipids_id": null
							},
							"LMST01010099": {
								"inchi_key": "BWGQUGBECNWWDB-PNAUCWDRSA-N",
								"swisslipids_id": null
							},
							"LMST01010174": {
								"inchi_key": "PESKGJQREUXSRR-UXIWKSIVSA-N",
								"swisslipids_id": null
							},
							"LMST01010205": {
								"inchi_key": "PESKGJQREUXSRR-JDIFZLMISA-N",
								"swisslipids_id": "SLM:000485358"
							},
							"LMST01010290": {
								"inchi_key": "DYIGMTKZUCRJAL-PHKHAJRTSA-N",
								"swisslipids_id": null
							},
							"LMST01010316": {
								"inchi_key": "MQDWBAYFXRRHRX-BPTFOWNUSA-N",
								"swisslipids_id": null
							},
							"LMST01010333": {
								"inchi_key": "BWGQUGBECNWWDB-IYXROPMCSA-N",
								"swisslipids_id": null
							},
							"LMST01010352": {
								"inchi_key": "UIMGHSAOLFTOBF-DPAQBDIFSA-N",
								"swisslipids_id": null
							},
							"LMST04030119": {
								"inchi_key": "GVTVGGOAMMTPEH-KKFSNPNRSA-N",
								"swisslipids_id": null
							},
							"LMST04030120": {
								"inchi_key": "RWHKYCDNDDPMGB-KKFSNPNRSA-N",
								"swisslipids_id": null
							}
						}
					},
					{
						"state": "Success",
						"normalized_name": "LPE P-19:0",
						"original_name": "LPE O 19:1p",
						"grammar": "Goslin",
						"lipidmaps_category": "GP",
						"lipidmaps_class": "Monoacylglycerophosphoethanolamines [GP0205]",
						"class_name": "LPE",
						"extended_class": "LPE-P",
						"lipid_level": "MOLECULAR_SPECIES",
						"mass": 479.33757553000004,
						"sum_formula": "C24H50NO6P",
						"lipidsmaps_data": "Standardized name not link with any entry in the LipidMaps Structure Database"
					},
					{
						"state": "Uncompleted",
						"original_name": "Acetyl acid",
						"messages": {
							"Shorthand2020": "Ac",
							"Goslin": "",
							"FattyAcids": "",
							"LipidMaps": "Ac",
							"SwissLipids": "Ac",
							"HMDB": "Ac"
						}
					}
				],
				"nb_success": 2,
				"nb_total_lipids": 3
			}