vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

QUALCHE INFORMAZIONE

L'API (interfaccia di programmazione di un'applicazione) permette di interrogare direttamente VOS⁴O utilizzando un'applicazione o un software di terze parti. Volendo, è possibile creare una pagina Web personale con il riscalamento del sistema solare, oppure è anche possibile scrivere uno script che interroghi direttamente il servizio o recuperare la tabella e le immagini generate attraverso un programma dedicato. Per l'interrogazione del servizio ci sono due metodi disponibili :

• Richiesta HTTP : interrogare direttamente il servizio con un programma per gestire il download da Internet in modo non interattivo come wget, curl o un oggetto XMLHttpRequest di un linguaggio Javascript.
• Servizio Web : interrogare VOS⁴O utilizzando un servizio Web basato sui protocolli (WS) SOAP+WSDL+HTTP.

L'utilizzo di API è libero e gratuito per un uso personale o pedagogico e non commerciale. Raccomandiamo fortemente di contattarci se volete sviluppare un'applicazione che utilizzi il servizio VOS⁴O in modo da essere informati sulla sua evoluzione.

Vi raccomandiamo inoltre di utilizzare il nostro sistema per la segnalazione di problemi per segnalare un mal funzionamento del servizio o per richiedere possibili miglioramenti.

Definizione della scala

La definizione della scala può essere data in 3 modi diversi :

x:y

per specificare un coefficiente moltiplicativo da applicare a tutte le unità di lunghezza. Ad esempio, la scala 1:1000000 (uno a un milione) permette di dividere per un milione le distanze e i diametri dei pianeti.

a(pianeta):x

per riscalare in base al valore x scelto per la distanza di un pianeta dato. Ad esempio, se il parametro unità=m (metro), allora la scala a(nettuno):7.22 permette di creare un sistema solare in cui la distanza Sole – Nettuno valga proprio 7.22 metri.

d(pianeta):x

per riscalare in base al valore x scelto per il diametro di una pianeta dato. Ad esempio, se il parametro unità=m (metro), allora la scala d(terra):1 permette di creare un sistema solare in cui il diametro della Terra valga proprio 1 metro.

Descrizione della tabella e delle immagini fornite

La tabella creata dal servizio VOS⁴O fornisce il diametro del Sole, i diametri dei pianeti e le loro distanze dal Sole riscalate in base all'unità scelta. La tabella fornisce anche le eccentricità delle orbite dei pianeti, così come le loro longitudini medie eliocentriche ad una certa epoca, espresse in gradi.

La prima figura generata dal servizio VOS⁴O mostra un grafico del sistema solare in scala in funzione dei parametri scelti. I pianeti sono disposti in scala logaritmica rispettando le loro distanze relative dal Sole, ed accanto a ciascuno di essi si trova il suo diametro e la sua distanza dal Sole, calcolata in funzione della scala e dell'unità scelte.

La seconda immagine è una visione dall'alto del sistema solare. Ogni pianeta è posizionato sulla sua orbita in funzione della sua longitudine media eliocentrica calcolata all'epoca richiesta. Il riferimento per le longitudini è la direzione del punto vernale (o equinozio di primavera), noto anche come punto γ.

Richiesta HTTP

L'utilizzo di un programma di download di dati da Internet non interattivo (wget, curl), o di un navigatore Internet, chiama il servizio attraverso il suo punto di accesso HTTP :

http://ssp.imcce.fr/webservices/vos4o/scale.php?[parameters]

dove [parameters] è una lista di parametri, definiti nella tabella 1, separati dal carattere &. Se nessun parametro viene cambiato, il servizio restituisce come risultato un sistema solare in scala in base ai valori indicati come default nella tabella 1.

^* Se il formato MIME richiesto è VOTABLE, il valore del parametro echelleauto è 0 indipendentemente dal valore fornito.

La risposta di una richiesta HTTP è costituita da una tabella e da una figura, in formato HTML, VOTable/XML o in testo semplice secondo la classe MIME scelta (argument -mime).

Esempi di richieste :

• Il sistema solare in scala 1:1000000 (uno a un milione).
• Il sistema solare se la distanza Sole - Nettuno fosse di 7.22 metri.
• Il sistema solare se il diametro della Terra valesse 1 metro.

Web service

Il servizio VOS⁴O può essere interrogato attraverso un Web service che si basa su dei protocolli SOAP+WSDL+HTTP che permettono un'interazione diretta tra la propria applicazione ed il servizio.

Web Service URI :

http://ssp.imcce.fr/webservices/vos4o/vos4o.php

Namespace o spazio dei nomi :

http://ssp.imcce.fr/webservices/vos4o

WSDL:

http://ssp.imcce.fr/webservices/vos4o/vos4o.php?wsdl

SOAP header:

nome dell'elemento header SOAP : clientID

contenuto dell'header SOAP : array('from' => 'NomProjet', 'hostip'=>'')

Metodo :

scale (inputArray)

Parametri in ingresso

I parametri in ingresso del metodo scale sono raggruppati in una tabella e hanno lo scopo di definire le variabili descritte nella tabella 2.

^* Se la classe MIME richiesta è VOTABLE, il parametro autoscale è false indipendentemente dal valore scelto.

Parametri in uscita

Il metodo 'scale' restituisce un oggetto che contiene i seguenti elementi :

'status'

Lo stato della risposta, basato sul codice HTTP : 200 = ok, 400 = richiesta sbagliata, 404 = non trovato, 500 = errore interno.

'ticket'

Stampa dell'orario della risposta.

'result'

Una stringa di caratteri contenenti la tabella e le figure del sistema solare riscalato.

Classe mime

A seconda della classe MIME selezionata, i dati vengono restituiti in uno dei seguenti formati :

votable

i dati sono scritti in un documento XML che segue lo standard VOTable dell' IVOA

html

i dati sono forniti in un documento HTML5

text

i dati sono scritti in un documento di tipo testo.

Come fare ?

Ci sono due modi per utilizzare questo servizio per creare una versione in scala del sistema solare: scrivere un client per inviare una richiesta al server VOS⁴O e quindi ricevere ed analizzare la risposta, oppure utilizzare un servizio di navigazione Web o un programma di trasferimento di dati come curl o wget. In quest'ultimo caso, bisogna eseguire il seguente comando da terminale :

$> curl "<URL>"

o

$> wget "<URL>"

in cui <URL> è già stato descritto nella sezione richiesta HTTP.

Per scrivere un programma di tipo client per chiamare il servizio VOS⁴O, è necessario scegliere un linguaggio che implementi il protocollo di comunicazione SOAP. Qui di seguito riportiamo un esempio di client scritto in PHP:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$param = array('scale' => 'd(Terre)=1.0',
               'autoscale' => true,
               'scalefactor' => 1.0,
               'unit' => 'm',
               'axis' => 'log',
               'lang' => 'it-it',
               'mime' => 'html',
               'epoch' => 'now');

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

try {
  // Instantiate the client
  $client = new SoapClient($uriwsdl, array('exceptions'=>1));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'');
  $client->__setSoapHeaders(array(
     new SOAPHeader($namespace, 'clientID', $header)
  ));  
  // Call the resolver method
  $response = $client->__soapCall('scale',array($param));
  // Display the results
  if ($param['mime'] == 'text') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/plain");
    $res = split(';', $response->result);
    $nbr = count($res);
    $newkey = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; };
  } else if ($param['mime'] == 'html') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/html");
    echo $response->result;
  } else {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/xml");
    echo $response->result."\n";
  }
} catch (SoapFault $fault) {
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} 
      (faultcode: {$fault->faultcode}, 
       faultstring: {$fault->faultstring})", E_USER_ERROR);
}