Commit d8f6b7eb02dc36b0c14600fb2ffb5fa93ceed201
1 parent
423f8749
Exists in
master
and in
108 other branches
Add API documentation
Showing
11 changed files
with
240 additions
and
45 deletions
Show diff stats
... | ... | @@ -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": "http://amda.irap.omp.eu/php/rest/", | |
6 | + "sampleUrl": "http://amda.irap.omp.eu/php/rest/" | |
7 | +} | ... | ... |
php/rest/auth.php
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['success']) { |
19 | 24 | echo $result['message']; |
20 | 25 | } |
21 | 26 | |
22 | -?> | |
23 | 27 | \ No newline at end of file |
28 | +?> | ... | ... |
php/rest/getDataset.php
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
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
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
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
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
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("id", $_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
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
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,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 | +?> | ... | ... |