Add API documentation

Nathanaël Jourdane
1 parent 423f8749
Showing 11 changed files with 240 additions and 45 deletions Show diff stats
php/rest/apidoc.json
php/rest/auth.php
php/rest/getDataset.php
php/rest/getObsDataTree.php
php/rest/getOrbites.php
php/rest/getParameter.php
php/rest/getParameterList.php
php/rest/getStatus.php
php/rest/getTimeTable.php
php/rest/getTimeTablesList.php
php/rest/isAlive.php
@@ -0,0 +1,7 @@
+{
+  "name": "AMDA web-services Rest API",
+  "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.",
+  "title": "AMDA Web-services Rest API documentation",
+  "url": "http://amda.irap.omp.eu/php/rest/",
+  "sampleUrl": "http://amda.irap.omp.eu/php/rest/"
+}
 <?php
 /**
- * @file getParameter.php
- * @brief  REST interface for service getParameter
+ * @api {get} auth.php auth
+ * @apiDescription Returns a token to use as an API parameter for *getParameter*, *getOrbites* and *getTimeTable*.
+ * @apiName auth
+ * @apiGroup webservices
  *
+ * @apiSuccess {String} token The API token.
  *
- * @version $Id:  $
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     4aca24fe814302a6dbceea3f4360c9b9
  */
 require_once '../config.php';
@@ -19,4 +24,4 @@ if ($result[&#39;success&#39;]) {
     echo $result['message'];
 }
-?>
 \ No newline at end of file
+?>
 <?php
+
 /**
- * @file getDataset.php
- * @brief  REST interface for service getDataset
+ * @api {get} getDataset.php getDataset
+ * @apiDescription Returns a token to use as an API parameter for *getParameter*, *getOrbites* and *getTimeTable*.
+ * @apiName getDataset
+ * @apiGroup webservices
  */
 //ini_set("allow_url_fopen", true);
 <?php
-/** 
-*   @file getObsDataTree.php 
-*   @brief  REST interface for service getObsDataTree
-*
-*   
-*   @version $Id:  $ 
-*/
+/**
+ * @api {get} getObsDataTree.php getObsDataTree
+ * @apiDescription Provides the hierarchy of public access data in AMDA.
+ * @apiName getObsDataTree
+ * @apiGroup webservices
+ *
+ * @apiSuccess {String} success true.
+ * @apiSuccess {String} workspace URLs of the XML files containing the list of "public" parameters in AMDA.
+ *
+ * @apiError {String} success false.
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultstring The error message.
+
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
+ *
+ * @apiErrorExample
+ *     HTTP/1.1 200 OK
+ *     {"success":false,"faultcode":"server00","faultstring":"Server error"}
+ */
   require_once '../config.php';
 <?php
 /**
- * @file getOrbites.php
- * @brief REST interface for service getOrbites
+ * @api {get} getOrbites.php getOrbites
+ * @apiDescription Provides the trajectory of a spacecraft during a period of time. The list of S/C for which an orbit
+ * is available is given below. Check on the current version of AMDA (amda.cdpp.eu) the coordinate systems, units, and
+ * time spans available for each S/C. For example, the orbit of INTERBALL-TAIL is only available in GSE or GSM
+ * coordinate systems and time ranges between 1995 and 2000.
+ * @apiName getOrbites
+ * @apiGroup webservices
+ *
+ * @apiParam {String} startTime Beginning of the time interval (ISO 8601 or UNIXTIME format).
+ * @apiParam {String} stopTime End of the time interval (ISO 8601 or UNIXTIME format)
+ * @apiParam {String} spacecraft Name of the spacecraft. Possible values: "ACE", "CASSINI", "CLUSTER1", "CLUSTER2",
+ * "CLUSTER3", "CLUSTER4", "DOUBLESTAR1", "GALILEO", "GEOTAIL", "IMP-8", "INTERBALL-TAIL", "ISEE-1", "ISEE-2", "MAVEN",
+ * "MESSENGER", "MEX", "MGS", "Pioneer_10", "Pioneer_11", "POLAR", "PVO "Stereo-A", "Stereo-B", "THEMIS-A",
+ * "THEMIS-B", "THEMIS-C", "THEMIS-D", "THEMIS-E", "ULYSSES", "VEX", "Voyager_1", "Voyager_2", "WIND".
+ * @apiParam {String} CoordinateSystem Identifier of the coordinate system to be used. Possible values: "Carrington",
+ * "CGM", "CPHIO", "DM", "EPHIO", "Equatorial", "GEI", "GEO", "GPHIO", "GSE", "GSEQ", "GSM", "HAE", "HCC", "HCI", "HCR",
+ * "HEE", "HEEQ", "HG", "HGI", "HPC", "HPR", "IPHIO", "J2000", "LGM", "MAG", "MFA", "MSO", "RTN", "SC", "SE", "SM",
+ * "SR", "SR2", "SSE", "SSE_L", "SpacecraftOrbitPlane", "VSO", "WGS84".
+ * @apiParam {String} [sampling] Sampling of data (seconds).
+ * @apiParam {String} [units] Units of orbits: radius or km. (Default = km) Possible values: "km", "Rs", "Rj", "Rca",
+ * "Rga", "Rio", "Reu", "Rv", "Rm", "Re", "AU".
+ * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
+ * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
+ * @apiParam {String} [gzip] "1" if the file must be compressed before delivery
+ * @apiParam {String} [outputFormat] Format of the returned file. Two options: "VOTable", "ASCII".
+ * @apiParam {String} [timeFormat] Format of time in the data files. Two options: "ISO8601", "UNIXTIME".
+ *
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} url_XYZ URL of the file containing the points.
+ *
+ * @apiError {String} success `false`
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultstring The error message.
+
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
+ *
+ * @apiErrorExample
+ *     HTTP/1.1 4xx OK
+ *     {"success":false,"faultcode":"server00","faultstring":"Server error"}
  */
 	require_once '../config.php';
@@ -25,4 +64,4 @@
 	echo json_encode($result);
-?>
 \ No newline at end of file
+?>
 <?php
 /**
- * @file getParameter.php
- * @brief  REST interface for service getParameter
+ * @api {get} getParameter.php getParameter
+ * @apiDescription Provides data corresponding to a parameter chosen by the user among those available in AMDA (common
+ * or user defined parameters).
+ * @apiName getParameter
+ * @apiGroup webservices
+ *
+ * @apiParam {String} startTime Beginning of the time interval (ISO 8601 or UNIXTIME format).
+ * @apiParam {String} stopTime End of the time interval (ISO 8601 or UNIXTIME format).
+ * @apiParam {String} parameterID Identifier of the parameter, as defined in the file returned by the *getParameterList*
+ * or *getObsDataTree* web-services.
+ * @apiParam {String} [sampling] Sampling of data (*in seconds*).
+ * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
+ * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
+ * @apiParam {String} [gzip] `1` if the file must be compressed before delivery.
+ * @apiParam {String} [outputFormat] Format of the returned file. Two options: `VOTable` and `ASCII`.
+ * @apiParam {String} [timeFormat] Format of time in the data files. Two options: `ISO8601` and `UNIXTIME`.
+ *
+ * @apiParamExample
+
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} dataFileURLs URL of the files matching the criteria. If the file is empty, there is no data
+ * matching these criteria.
+ *
+ * @apiError {String} success `false`
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultstring The error message.
+ *
+ * @apiSuccessExample
+ *     HTTP/1.1 200 OK
+ *     http://cdpp1.cesr.fr/AMDA/data/WSRESULT/b_it-821664000-821750400-.xml
+ *
+ * @apiErrorExample
+ * HTTP/1.1 4xx OK
+ * {"success":false,"faultcode":"server00","faultstring":"Server error"}
+
  */
 	require_once '../config.php';
@@ -24,4 +57,4 @@
 	}
 	echo json_encode($result);
-?>
 \ No newline at end of file
+?>
 <?php
-  
-/** 
-*   @file getParameterList.php 
-*   @brief  REST interface for service getParameterList
-*
-*   
-*   @version $Id:  $ 
-*/
+
+/**
+ * @api {get} getParameterList.php getParameterList
+ * @apiDescription Provides the hierarchy of parameters belonging to a user in AMDA.
+ * @apiName getParameterList
+ * @apiGroup webservices
+ *
+ * @apiParam {String} userID Identifier of the user in AMDA.
+ * @apiParam {String} password password of the user in AMDA.
+ *
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} url_XYZ URL of the file containing the points.
+ *
+ * @apiError {String} success `false`
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultstring The error message.
+
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     http://amda.irap.omp.eu/AMDA/data/WSRESULT/obsdatatree_impex_20180727_AmdaLocalDataBaseParameters.xml
+ *
+ * @apiErrorExample
+ *     HTTP/1.1 4xx OK
+ *     {"success":false,"faultcode":"server00","faultstring":"Server error"}
+ */
   require_once '../config.php';
 <?php
 /**
- * @file getStatus.php
- * @brief  REST interface for service getParameter
+ * @api {get} getStatus.php getStatus
+ * @apiDescription Get the current status of the request according to a process ID.
+ * @apiName getStatus
+ * @apiGroup webservices
  *
- * @version $Id:  $
+ * @apiParam {String} id process ID.
+ *
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} [dataFileURLs] URLs of results data files. If no URLs - no data for required parameters.
+ * @apiSuccess {String} [plotURL] URLs of results plot files. If no URLs - no data for required parameters.
+ * @apiSuccess {String} [status] The status code. Possible values: "in progress, "error".
+ *
+ * @apiError {String} success `false`
+ *
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {"success":true,"status":"done","dataFileURLs":"http:\/\/amda.irap.omp.eu\/AMDA\/\/data\/WSRESULT\/"}
+ *
+ * @apiErrorExample
+ *     HTTP/1.1 200 OK
+ *     {"success":false,"message":"You must provide a job id"}
  */
 require_once '../config.php';
@@ -15,4 +32,4 @@ if (!key_exists(&quot;id&quot;, $_GET)) {
 	$amda_ws = new WebServer();
 	$result = $amda_ws->getStatus($_GET);
 }
-echo json_encode($result);
 \ No newline at end of file
+echo json_encode($result);
 <?php
-  
-/** 
-*   @file getTimeTable.php
-*   @brief  REST interface for service getTimeTable
-*
-*   
-*   @version $Id:  $ 
-*/
- require_once '../config.php';
+/**
+ * @api {get} getTimeTable.php getTimeTable
+ * @apiDescription Provides the contents of a Time Table (TT).
+ * @apiName getTimeTable
+ * @apiGroup webservices
+ *
+ * @apiParam {String} ttID Identifier of the Time Table, the « getTimeTableList » service.
+ * @apiParam {String} [userID] Identifier of the user in AMDA (*mandatory for user owned data*)
+ * @apiParam {String} [password] Password of the user in AMDA (*mandatory for user owned data*)
+ *
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} ttFileURL URL of the XML file containing the Time Table (VOTable format)
+ *
+ * @apiSuccessExample Success-Response:
+ * HTTP/1.1 200 OK
+ * http://cdpp1.cesr.fr/AMDA/data/WSRESULT/getTimeTable_impex_sharedtt_0.xml
+ *
+ * @apiError {String} success `false`
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultstring The error message.
+ *
+ * @apiErrorExample getTimeTable(ttID=sharedtt_0)
+ * HTTP/1.1 4xx OK
+ * {"success":false,"faultcode":"server00","faultstring":"Server error"}
+ */
+
+require_once '../config.php';
   $amda_ws = new WebServer();
 <?php
-  
-/** 
-*   @file getTimeTablesList.php
-*   @brief  REST interface for service getTimeTablesList
-*/
+
+/**
+ * @api {get} getTimeTablesList.php getTimeTableList
+ * @apiDescription Provides the private list of Time Tables (Time Table or TT) owned by a user. When called without
+ * userID, this web-service returns the list of shared Time Tables.
+ *
+ * @apiName getTimeTableList
+ * @apiGroup webservices
+ *
+ * @apiParam {String} [userID] Identifier of the user in AMDA.
+ * @apiParam {String} [password] Password of the user in AMDA.
+ *
+ * @apiSuccess {String} success `true`
+ * @apiSuccess {String} TimeTablesList URL of the XML file, which contains the list of Time Tables.
+ *
+ * @apiError {String} success `false`
+ * @apiError {String} faultcode The error code.
+ * @apiError {String} faultcode The error message.
+ *
+ * @apiSuccessExample Success-Response:
+ * HTTP/1.1 200 OK
+ * http://cdpp1.cesr.fr/AMDA/data/WSRESULT/getTimeTablesList_gangloff.xml
+ *
+ * @apiErrorExample
+ *     HTTP/1.1 4xx OK
+ *     {"success":false,"faultcode":"server00","faultstring":"Server Error: AMDA Login procedure failed"}
+ */
 	require_once '../config.php';
@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * @api {get} isalive.php isAlive
+ * @apiDescription Used to check whether AMDA services are available or not.
+ * @apiName isAlive
+ * @apiGroup webservices
+ *
+ * @apiParam {Number} id Users unique ID.
+ *
+ * @apiSuccess {Boolean} always `true`.
+ *
+ * @apiSuccessExample Success-Response:
+ *     HTTP/1.1 200 OK
+ *     {"alive":true}
+ */
+
+echo json_encode(['alive' => true]);
+
+?>