CDPP / AMDA_IHM

Commit f54b897c3fc73ca7afdd30de39b28e26bf3b8a2e

Authored by Myriam Bouchemit
2 parents 9e65752e 1f8614f3
Exists in master and in 108 other branches 10098, 10178, 5390, 6629, 6728, 6920, 7494, 7497, 7616, 8459, 8528, 8928, 9014, 9016Bis, 9017, 9049, 9084, 9259, 9326, 9345, 9505, 9660, 9750, 9750.bck, 9800, 9980, FER_10285, FER_10400, FER_10435, FER_10557, FER_10663, FER_10765, FER_10828, FER_10828_2, FER_10829, FER_10836, FER_10852, FER_10934, FER_11100, FER_11242, FER_11478, FER_11500, FER_11537, FER_11586, FER_11588, FER_5119, FER_5165, FER_6265, FER_6860, FER_6899, FER_6951, FER_7618, FER_7862, FER_8455, FER_9629, FER_9660, FER_9915, FER_CR41, FER_CR42, FER_CR43, FER_TFCat, Histo1D2D, MAZ_10936, MAZ_11362, MAZ_11427, MAZ_6018, MAZ_9016_New, MAZ_FIX_9016, New_ColorMaps, SpeasyGet, alias, amdadev, amdadev_test, anr_tempete, catalog-histo, create-user, cu2022, density_maps, develop, epn-tap, expression-parser-bre, frames-transformation, hapi, homePage, master_vge, minimize, mlplasmas, multiplot, new-save-plot-request, openam, plot-request, plot-request-update, plot-tt-catalog, remoteData, rm_5118, rm_5776, rm_6912, rm_6912_bis, rm_7926, rm_8932, save-other-requests, save-plot, save-plot-request, shared-objects-updater, special-params, sum-components-indexes, test-merge, ws_get_catalog

Merge branch 'api-doc' into 'master' 

Api doc

Add documentation and necessary files to build the API documentation.

See merge request !27
Showing 13 changed files with 254 additions and 45 deletions   Show diff stats
Inline Side-by-side
php/my_config.template.php
  Diff comments   View file @f54b897
... ... @@ -32,4 +32,6 @@ define('NEWMETA', '{:NEWMETA:}');
32 32 define('AMDA_SPASE_INTERFACE', '{:AMDA_SPASE_INTERFACE:}');
33 33 define('AMDAINTERNALDIR', '{:AMDAINTERNALDIR:}');
34 34  
  35 +define('REST_API_URL', '{:REST_API_URL:}');
  36 +define('API_DOC_PATH', '{:API_DOC_PATH:}');
35 37 ?>
... ...
php/rest/apidoc.json 0 → 100644
  Diff comments   View file @f54b897
... ... @@ -0,0 +1,7 @@
  1 +{
  2 + "name": "AMDA web-services Rest API",
  3 + "description": "The web-services provided by AMDA aim at giving to a user access public data as well as its private data. These data may be private or shared Time Tables, public or user-defined parameters. All these webservices are also available through a SOAP interface.",
  4 + "title": "AMDA Web-services Rest API documentation",
  5 + "url": "{:REST_API_URL:}/php/rest/",
  6 + "sampleUrl": "{:REST_API_URL:}/php/rest/"
  7 +}
... ...
php/rest/auth.php
  Diff comments   View file @f54b897
1 1 <?php
2 2  
3 3 /**
4   - * @file getParameter.php
5   - * @brief REST interface for service getParameter
  4 + * @api {get} auth.php auth
  5 + * @apiDescription Returns a token to use as an API parameter for *getParameter*, *getOrbites* and *getTimeTable*.
  6 + * @apiName auth
  7 + * @apiGroup webservices
6 8 *
  9 + * @apiSuccess {String} token The API token.
7 10 *
8   - * @version $Id: $
  11 + * @apiSuccessExample Success-Response:
  12 + * HTTP/1.1 200 OK
  13 + * 4aca24fe814302a6dbceea3f4360c9b9
9 14 */
10 15  
11 16 require_once '../config.php';
... ... @@ -19,4 +24,4 @@ if ($result[&#39;success&#39;]) {
19 24 echo $result['message'];
20 25 }
21 26  
22   -?>
23 27 \ No newline at end of file
  28 +?>
... ...
php/rest/getDataset.php
  Diff comments   View file @f54b897
1 1 <?php
  2 +
2 3 /**
3   - * @file getDataset.php
4   - * @brief REST interface for service getDataset
  4 + * @api {get} getDataset.php getDataset
  5 + * @apiDescription Returns a token to use as an API parameter for *getParameter*, *getOrbites* and *getTimeTable*.
  6 + * @apiName getDataset
  7 + * @apiGroup webservices
5 8 */
6 9  
7 10 //ini_set("allow_url_fopen", true);
... ...
php/rest/getObsDataTree.php
  Diff comments   View file @f54b897
1 1 <?php
2 2  
3   -/**
4   -* @file getObsDataTree.php
5   -* @brief REST interface for service getObsDataTree
6   -*
7   -*
8   -* @version $Id: $
9   -*/
  3 +/**
  4 + * @api {get} getObsDataTree.php getObsDataTree
  5 + * @apiDescription Provides the hierarchy of public access data in AMDA.
  6 + * @apiName getObsDataTree
  7 + * @apiGroup webservices
  8 + *
  9 + * @apiSuccess {String} success true.
  10 + * @apiSuccess {String} workspace URLs of the XML files containing the list of "public" parameters in AMDA.
  11 + *
  12 + * @apiError {String} success false.
  13 + * @apiError {String} faultcode The error code.
  14 + * @apiError {String} faultstring The error message.
  15 +
  16 + * @apiSuccessExample Success-Response:
  17 + * HTTP/1.1 200 OK
  18 + * http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
  19 + *
  20 + * @apiErrorExample
  21 + * HTTP/1.1 200 OK
  22 + * {"success":false,"faultcode":"server00","faultstring":"Server error"}
  23 + */
10 24  
11 25 require_once '../config.php';
12 26  
... ...
php/rest/getOrbites.php
  Diff comments   View file @f54b897
1 1 <?php
2 2  
3 3 /**
4   - * @file getOrbites.php
5   - * @brief REST interface for service getOrbites
  4 + * @api {get} getOrbites.php getOrbites
  5 + * @apiDescription Provides the trajectory of a spacecraft during a period of time. The list of S/C for which an orbit
  6 + * is available is given below. Check on the current version of AMDA (amda.cdpp.eu) the coordinate systems, units, and
  7 + * time spans available for each S/C. For example, the orbit of INTERBALL-TAIL is only available in GSE or GSM
  8 + * coordinate systems and time ranges between 1995 and 2000.
  9 + * @apiName getOrbites
  10 + * @apiGroup webservices
  11 + *
  12 + * @apiParam {String} startTime Beginning of the time interval (ISO 8601 or UNIXTIME format).
  13 + * @apiParam {String} stopTime End of the time interval (ISO 8601 or UNIXTIME format)
  14 + * @apiParam {String} spacecraft Name of the spacecraft. Possible values: "ACE", "CASSINI", "CLUSTER1", "CLUSTER2",
  15 + * "CLUSTER3", "CLUSTER4", "DOUBLESTAR1", "GALILEO", "GEOTAIL", "IMP-8", "INTERBALL-TAIL", "ISEE-1", "ISEE-2", "MAVEN",
  16 + * "MESSENGER", "MEX", "MGS", "Pioneer_10", "Pioneer_11", "POLAR", "PVO "Stereo-A", "Stereo-B", "THEMIS-A",
  17 + * "THEMIS-B", "THEMIS-C", "THEMIS-D", "THEMIS-E", "ULYSSES", "VEX", "Voyager_1", "Voyager_2", "WIND".
  18 + * @apiParam {String} CoordinateSystem Identifier of the coordinate system to be used. Possible values: "Carrington",
  19 + * "CGM", "CPHIO", "DM", "EPHIO", "Equatorial", "GEI", "GEO", "GPHIO", "GSE", "GSEQ", "GSM", "HAE", "HCC", "HCI", "HCR",
  20 + * "HEE", "HEEQ", "HG", "HGI", "HPC", "HPR", "IPHIO", "J2000", "LGM", "MAG", "MFA", "MSO", "RTN", "SC", "SE", "SM",
  21 + * "SR", "SR2", "SSE", "SSE_L", "SpacecraftOrbitPlane", "VSO", "WGS84".
  22 + * @apiParam {String} [sampling] Sampling of data (seconds).
  23 + * @apiParam {String} [units] Units of orbits: radius or km. (Default = km) Possible values: "km", "Rs", "Rj", "Rca",
  24 + * "Rga", "Rio", "Reu", "Rv", "Rm", "Re", "AU".
  25 + * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
  26 + * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
  27 + * @apiParam {String} [gzip] "1" if the file must be compressed before delivery
  28 + * @apiParam {String} [outputFormat] Format of the returned file. Two options: "VOTable", "ASCII".
  29 + * @apiParam {String} [timeFormat] Format of time in the data files. Two options: "ISO8601", "UNIXTIME".
  30 + *
  31 + * @apiSuccess {String} success `true`
  32 + * @apiSuccess {String} url_XYZ URL of the file containing the points.
  33 + *
  34 + * @apiError {String} success `false`
  35 + * @apiError {String} faultcode The error code.
  36 + * @apiError {String} faultstring The error message.
  37 +
  38 + * @apiSuccessExample Success-Response:
  39 + * HTTP/1.1 200 OK
  40 + * http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
  41 + *
  42 + * @apiErrorExample
  43 + * HTTP/1.1 4xx OK
  44 + * {"success":false,"faultcode":"server00","faultstring":"Server error"}
6 45 */
7 46  
8 47 require_once '../config.php';
... ... @@ -25,4 +64,4 @@
25 64  
26 65 echo json_encode($result);
27 66  
28   -?>
29 67 \ No newline at end of file
  68 +?>
... ...
php/rest/getParameter.php
  Diff comments   View file @f54b897
1 1 <?php
2 2  
3 3 /**
4   - * @file getParameter.php
5   - * @brief REST interface for service getParameter
  4 + * @api {get} getParameter.php getParameter
  5 + * @apiDescription Provides data corresponding to a parameter chosen by the user among those available in AMDA (common
  6 + * or user defined parameters).
  7 + * @apiName getParameter
  8 + * @apiGroup webservices
  9 + *
  10 + * @apiParam {String} startTime Beginning of the time interval (ISO 8601 or UNIXTIME format).
  11 + * @apiParam {String} stopTime End of the time interval (ISO 8601 or UNIXTIME format).
  12 + * @apiParam {String} parameterID Identifier of the parameter, as defined in the file returned by the *getParameterList*
  13 + * or *getObsDataTree* web-services.
  14 + * @apiParam {String} [sampling] Sampling of data (*in seconds*).
  15 + * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
  16 + * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
  17 + * @apiParam {String} [gzip] `1` if the file must be compressed before delivery.
  18 + * @apiParam {String} [outputFormat] Format of the returned file. Two options: `VOTable` and `ASCII`.
  19 + * @apiParam {String} [timeFormat] Format of time in the data files. Two options: `ISO8601` and `UNIXTIME`.
  20 + *
  21 + * @apiParamExample
  22 +
  23 + * @apiSuccess {String} success `true`
  24 + * @apiSuccess {String} dataFileURLs URL of the files matching the criteria. If the file is empty, there is no data
  25 + * matching these criteria.
  26 + *
  27 + * @apiError {String} success `false`
  28 + * @apiError {String} faultcode The error code.
  29 + * @apiError {String} faultstring The error message.
  30 + *
  31 + * @apiSuccessExample
  32 + * HTTP/1.1 200 OK
  33 + * http://cdpp1.cesr.fr/AMDA/data/WSRESULT/b_it-821664000-821750400-.xml
  34 + *
  35 + * @apiErrorExample
  36 + * HTTP/1.1 4xx OK
  37 + * {"success":false,"faultcode":"server00","faultstring":"Server error"}
  38 +
6 39 */
7 40  
8 41 require_once '../config.php';
... ... @@ -24,4 +57,4 @@
24 57 }
25 58  
26 59 echo json_encode($result);
27   -?>
28 60 \ No newline at end of file
  61 +?>
... ...
php/rest/getParameterList.php
  Diff comments   View file @f54b897
1 1 <?php
2   -
3   -/**
4   -* @file getParameterList.php
5   -* @brief REST interface for service getParameterList
6   -*
7   -*
8   -* @version $Id: $
9   -*/
  2 +
  3 +/**
  4 + * @api {get} getParameterList.php getParameterList
  5 + * @apiDescription Provides the hierarchy of parameters belonging to a user in AMDA.
  6 + * @apiName getParameterList
  7 + * @apiGroup webservices
  8 + *
  9 + * @apiParam {String} userID Identifier of the user in AMDA.
  10 + * @apiParam {String} password password of the user in AMDA.
  11 + *
  12 + * @apiSuccess {String} success `true`
  13 + * @apiSuccess {String} url_XYZ URL of the file containing the points.
  14 + *
  15 + * @apiError {String} success `false`
  16 + * @apiError {String} faultcode The error code.
  17 + * @apiError {String} faultstring The error message.
  18 +
  19 + * @apiSuccessExample Success-Response:
  20 + * HTTP/1.1 200 OK
  21 + * http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
  22 + *
  23 + * @apiErrorExample
  24 + * HTTP/1.1 4xx OK
  25 + * {"success":false,"faultcode":"server00","faultstring":"Server error"}
  26 + */
10 27  
11 28 require_once '../config.php';
12 29  
... ...
php/rest/getStatus.php
  Diff comments   View file @f54b897
1 1 <?php
2 2  
3 3 /**
4   - * @file getStatus.php
5   - * @brief REST interface for service getParameter
  4 + * @api {get} getStatus.php getStatus
  5 + * @apiDescription Get the current status of the request according to a process ID.
  6 + * @apiName getStatus
  7 + * @apiGroup webservices
6 8 *
7   - * @version $Id: $
  9 + * @apiParam {String} id process ID.
  10 + *
  11 + * @apiSuccess {String} success `true`
  12 + * @apiSuccess {String} [dataFileURLs] URLs of results data files. If no URLs - no data for required parameters.
  13 + * @apiSuccess {String} [plotURL] URLs of results plot files. If no URLs - no data for required parameters.
  14 + * @apiSuccess {String} [status] The status code. Possible values: "in progress, "error".
  15 + *
  16 + * @apiError {String} success `false`
  17 + *
  18 + * @apiSuccessExample Success-Response:
  19 + * HTTP/1.1 200 OK
  20 + * {"success":true,"status":"done","dataFileURLs":"http:\/\/amda.irap.omp.eu\/AMDA\/\/data\/WSRESULT\/"}
  21 + *
  22 + * @apiErrorExample
  23 + * HTTP/1.1 200 OK
  24 + * {"success":false,"message":"You must provide a job id"}
8 25 */
9 26  
10 27 require_once '../config.php';
... ... @@ -15,4 +32,4 @@ if (!key_exists(&quot;id&quot;, $_GET)) {
15 32 $amda_ws = new WebServer();
16 33 $result = $amda_ws->getStatus($_GET);
17 34 }
18   -echo json_encode($result);
19 35 \ No newline at end of file
  36 +echo json_encode($result);
... ...
php/rest/getTimeTable.php
  Diff comments   View file @f54b897
1 1 <?php
2   -
3   -/**
4   -* @file getTimeTable.php
5   -* @brief REST interface for service getTimeTable
6   -*
7   -*
8   -* @version $Id: $
9   -*/
10 2  
11   - require_once '../config.php';
  3 +/**
  4 + * @api {get} getTimeTable.php getTimeTable
  5 + * @apiDescription Provides the contents of a Time Table (TT).
  6 + * @apiName getTimeTable
  7 + * @apiGroup webservices
  8 + *
  9 + * @apiParam {String} ttID Identifier of the Time Table, the « getTimeTableList » service.
  10 + * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
  11 + * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
  12 + *
  13 + * @apiSuccess {String} success `true`
  14 + * @apiSuccess {String} ttFileURL URL of the XML file containing the Time Table (VOTable format)
  15 + *
  16 + * @apiSuccessExample Success-Response:
  17 + * HTTP/1.1 200 OK
  18 + * http://cdpp1.cesr.fr/AMDA/data/WSRESULT/getTimeTable_impex_sharedtt_0.xml
  19 + *
  20 + * @apiError {String} success `false`
  21 + * @apiError {String} faultcode The error code.
  22 + * @apiError {String} faultstring The error message.
  23 + *
  24 + * @apiErrorExample getTimeTable(ttID=sharedtt_0)
  25 + * HTTP/1.1 4xx OK
  26 + * {"success":false,"faultcode":"server00","faultstring":"Server error"}
  27 + */
  28 +
  29 +require_once '../config.php';
12 30  
13 31 $amda_ws = new WebServer();
14 32  
... ...
php/rest/getTimeTablesList.php
  Diff comments   View file @f54b897
1 1 <?php
2   -
3   -/**
4   -* @file getTimeTablesList.php
5   -* @brief REST interface for service getTimeTablesList
6   -*/
  2 +
  3 +/**
  4 + * @api {get} getTimeTablesList.php getTimeTableList
  5 + * @apiDescription Provides the private list of Time Tables (Time Table or TT) owned by a user. When called without
  6 + * userID, this web-service returns the list of shared Time Tables.
  7 + *
  8 + * @apiName getTimeTableList
  9 + * @apiGroup webservices
  10 + *
  11 + * @apiParam {String} [userID] Identifier of the user in AMDA.
  12 + * @apiParam {String} [password] Password of the user in AMDA.
  13 + *
  14 + * @apiSuccess {String} success `true`
  15 + * @apiSuccess {String} TimeTablesList URL of the XML file, which contains the list of Time Tables.
  16 + *
  17 + * @apiError {String} success `false`
  18 + * @apiError {String} faultcode The error code.
  19 + * @apiError {String} faultcode The error message.
  20 + *
  21 + * @apiSuccessExample Success-Response:
  22 + * HTTP/1.1 200 OK
  23 + * http://cdpp1.cesr.fr/AMDA/data/WSRESULT/getTimeTablesList_gangloff.xml
  24 + *
  25 + * @apiErrorExample
  26 + * HTTP/1.1 4xx OK
  27 + * {"success":false,"faultcode":"server00","faultstring":"Server Error: AMDA Login procedure failed"}
  28 + */
7 29  
8 30 require_once '../config.php';
9 31  
... ...
php/rest/isAlive.php 0 → 100644
  Diff comments   View file @f54b897
... ... @@ -0,0 +1,20 @@
  1 +<?php
  2 +
  3 +/**
  4 + * @api {get} isalive.php isAlive
  5 + * @apiDescription Used to check whether AMDA services are available or not.
  6 + * @apiName isAlive
  7 + * @apiGroup webservices
  8 + *
  9 + * @apiParam {Number} id Users unique ID.
  10 + *
  11 + * @apiSuccess {Boolean} always `true`.
  12 + *
  13 + * @apiSuccessExample Success-Response:
  14 + * HTTP/1.1 200 OK
  15 + * {"alive":true}
  16 + */
  17 +
  18 +echo json_encode(['alive' => true]);
  19 +
  20 +?>
... ...
scripts/apiDoc.php 0 → 100644
  Diff comments   View file @f54b897
... ... @@ -0,0 +1,12 @@
  1 +<?php
  2 +require_once dirname(__FILE__) . '/../php/config.php';
  3 +
  4 +$restFolderPath = AMDA_IHM . "php/rest";
  5 +$apidocConfigFile = $restFolderPath . "apidoc.json";
  6 +$tempConfigFile = tempnam(sys_get_temp_dir(), 'apidoc.json');
  7 +
  8 +$apidocConfig = str_replace("{:REST_API_URL:}", REST_API_URL, file_get_contents($apidocConfigFile));
  9 +file_put_contents($tempConfigFile, $apidocConfig);
  10 +
  11 +echo exec("apidoc -v -c $tempConfigFile -i $restFolderPath -o " . API_DOC_PATH);
  12 +?>
... ...