Skybot3D

getAvailability

Availability of Skybot3D service

The method getAvailability is intended to people who need to know the availability of the Skybot3D service.

HTTP Request

If you are a software/solutions developer, you might want to include the Skybot3D getAvailability service into your application. This can be done by using the web service method or by using the following HTTP request:
https://ssp.imcce.fr/webservices/skybot3d/api/getAvailability.php?[parameters]
where [parameters] is a list of parameters separated by the character &. The allowed parameters are:
ParameterDefinitionLimits
-mime=<string> Mime type of the results votable | html | text | json
-project=<string> Name of one of the Skybot3D databases sbot2 (default) | sbotRosetta | sbotKepler | sbotEarthL2 | sbotTESS
-from=<string> Word which define the name of the caller application,
or which describes the request
any short string
(no space character)

The output results are described in the following section, and are available in VOTable (default), HTML, plain text format, and JSON object (cf. examples). The -mime argument is optionnal and its value can be omitted (just write nothing or ...&-mime= without value). In this case, the output is displayed as VOTable.

Web service

The Skybot3D Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the Skybot3D service. Here is the useful information to invoke the Skybot3D getAvailability method:
Web Service URI:
https://ssp.imcce.fr/webservices/skybot3d/skybot3d.php
Namespace:
https://ssp.imcce.fr/webservices/skybot3d
WSDL:
https://ssp.imcce.fr/webservices/skybot3d/skybot3d.php?wsdl
SOAP header:
name of the SOAP header element: clientID
SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
Method:
getavailability (inputArray)
The input parameter of the method is an array which must contained the following parameter:
VariableTypeUnitsLimits or valuesDefaultComment
mime string - votable | html | text | json votable Mime type of the results
project string - sbot2 | sbotRosetta | sbotKepler | sbotEarthL2 | sbotTESS sbot2 Name of one of the Skybot3D databases

The output of the status method is an object containing the following attributes:

'flag'
the status of the response: flag=1 means ok; flag=0 or flag=-1 mean that an error occured
'status'
the HTTP status-code of the response (e.g. 400: bad request, 422: Unprocessable Entity, 500: internal error)
'ticket'
the Unix timestamp of the response which can be useful to stamp the request
'result'
a string which contains information which are conformed to the "availability 0.2" schema (IVOA Support Interfaces and Basic Profile)
Depending on the selected mime type, the output is formatted as:
votable
the data are written in the IVOA standard VOTable format
html
the data are transformed from VOTable to HTML by XSLT processing (Skybot3D XSL style sheet)
text
the data are returned in plain text where each value is separated by the pipe '|' character
json
the data are written in a JSON object.

Query examples

Output results

The output parameters of the method is a string which contains information which are conformed to the "availability 0.2" schema (IVOA Support Interfaces and Basic Profile):

No.DefinitionValue
1 Availability 'available', 'unavailable'
2 Uptime: time since last restart of service duration
3 ValidTo: next scheduled down-time, if known, nil=true if unknown dateTime (ISO format)
4 ContactDetails: detailed contact string

Structure of the output JSON object

When the output mime type is the JSON data-interchange format, the availability of Skybot3D service is encapsulated into a structure defined as follows:
{ 
  "availability": {string}, 
  "uptime": {dateTime}, 
  "validto": {string}, 
  "contact": {string} 
}

How to consume

You have two ways to use the Skybot3D web service: by writting a client to send requests to the Skybot3D server and to receive and analyze the response, or by using a command line interface and a data transfert program such as curl or wget. For that, just execute one of the following commands in a console:
$> curl "<URL>"
or
$> wget "<URL>"
where <URL> is described in section HTTP request.

In order to help you to invoke the Skybot3D web service, we provide some clients written in differents languages. Here are some detailed explanations to write a client with PHP and SOAP which invokes the getAvailability method:

1/ Provide the input parameters which are mandatory for the service:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$param = array('mime' => "text");

2/ Define the SOAP options, the namespace and the WSDL URI of Skybot3D web service:

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// Skybot3D namespace
$namespace = 'https://ssp.imcce.fr/webservices/skybot3d';
// Skybot3D WSDL
$uriwsdl = $namespace.'/skybot3d.wsdl';

3/ Create a SoapClient object in WSDL mode, set the SOAP header, then call the method and catch exceptions:

try {
   // Constructs the client
   $client = new SoapClient($uriwsdl, array('exceptions'=>1));
   // SOAP header
   $header = array('from'=>$from, 'hostip'=>'', 'lang'=>'en');
   $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));  
   // Call the resolver method
   $response = $client->__soapCall('getAvailability',$param);
   // Display the results
   if ($param['mime'] == 'text') {
      header("HTTP/1.0 200");
      header("Content-Type: text/plain");
      $res = explode(';', $response->result);
      $nbr = count($res);
      $newkey = array_keys($res);
      for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]].PHP_EOL; }
    } else if ($param['mime'] == 'json') {
      header("HTTP/1.0 200");
      header("Content-Type: application/json");
      echo $response->result;
   } else {
      header("HTTP/1.0 200");
      header("Content-Type: text/xml;content=x-votable");
      echo $response->result;
   }
} 
catch (SoapFault $fault) 
{
   trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode},
                               faultstring: {$fault->faultstring})", E_USER_ERROR);
}