ANNEXE A3.2

Programmer et utiliser les API HTML

Si vous décidez d'utiliser l'API HTML du Portail de découverte de GéoConnexions dans votre application, vous devrez tenir compte de plusieurs aspects de la programmation. La présente annexe décrit :

• les méthodes et principes généraux de la programmation des API HTML;
  
  
• la structure générale et la signification des paramètres et des valeurs;
  
  
• les conditions d'inclusion des paramètres; et
  
  
• les spécifications de l'API HTML.
  
  

A3.2.1 Méthodes HTTP utilisées par les API

Les méthodes HTTP GET ou POST peuvent être utilisées pour soumettre des paramètres à l'API. Aucun changement n'est requis en fonction des paramètres ou des valeurs. Les deux méthodes de soumission sont automatiquement reconnues et traitées par l'API.

Il faut remarquer que les URL, les paramètres et les valeurs sont actuellement sensibles à la casse (c.-à-d. les majuscules ou minuscules de la requête doivent correspondre exactement à celles des valeurs attendues). Dans un avenir prochain, le problème de sensibilité à la casse sera résolu.

A3.2.2 Forme et adresse URL d'un appel API GET dans l'interface HTML

Une interface CGI produit les résultats pour une requête API. La forme générale (modèle) de la requête API GET (hyperlien) à l'appel CGI est définie ci-dessous :

Dans le URL ci-dessus, « mode », « paramètre » et « valeur » sont des variables fictives que vous devez remplacer par le texte approprié. Les valeurs de ces variables déterminent l'action qui sera effectuée par le système et, par conséquent, le résultat affiché. Le point d'interrogation (?), le symbole d'égalité (=) et la perluète (&) sont des caractères que vous devez inclure dans l'URL comme dans les exemples ci-dessus.

Le présent manuel définit les « modes » pour chaque interface dans l'interface HTML.

Il faut noter que certains navigateurs n'envoient qu'un nombre limité de caractères quand ils utilisent la méthode GET. Avant d'intégrer une URL de la méthode GET dans une page HTML, vous devriez faire l'essai de l'URL avec plusieurs types de navigateurs afin de vous assurer que la longueur de l'URL ne pose aucun problème à ces navigateurs.

A3.2.3 Caractères utilisables dans une URL HTTP « GET » de l'API

Pour toute URL dont les paramètres sont envoyés à l'aide de la méthode HTTP GET, certains caractères sont considérés comme peu sûrs ou réservés et ils doivent être codés à l'aide de séquences d'échappement. Ces séquences d'échappement prennent la forme %<caractère ASCII-valeurhexadécimale>.

Les caractères peu sûrs sont ceux qui peuvent être interprétés par un navigateur ou un serveur Web différemment de ce qui est prévu. Les caractères réservés sont ceux qui ont une signification particulière à l'intérieur d'une URL et qu'on doit coder pour qu'ils ne soient pas confondus avec leur sens propre.

Le tableau 7, Caractères utilisables dans une URL HTTP « GET » de l'API, présente une liste de ces caractères et de leurs séquences d'échappement. Il faut noter que les lettres alphabétiques du code ne sont pas sensibles à la casse.

Tableau 7 Caractères utilisables dans une URL HTTP « GET » de l'API

Ainsi, pour préciser la page sujet intitulée :

Vous devez ajouter le code de caractères approprié, dans ce cas / = %2f:

Veuillez noter que le trait d'union est l'un des caractères non alphabétiques qui peuvent être utilisés sans recourir au code hexadécimal.

Vous n'avez pas à tenir compte de l'encodage si vous êtes disposé à mettre en place une fonction JavaScript, nommée escape(), qui peut faire l'encodage pour vous.

Les requêtes HTTP POST n'ont pas besoin d'être en code hexadécimal.

A3.2.4 Forme d'un appel POST de l'API dans l'interface HTML

Tout comme pour les appels GET, paramètre et valeur sont des variables fictives que vous devez remplacer par un texte approprié. Les valeurs de ces variables déterminent l'action qui sera effectuée par le système, de même que le résultat affiché.

Dans l'interface HTML, la forme générale de l'appel POST de l'API du Portail de découverte de GéoConnexions est définie ci-dessous :

<FORM ACTION="http://geodiscover.cgdi.ca/gdp/[Mode]" METHOD="POST">

<INPUT TYPE="hidden" NAME="Paramètre" Valeur="Valeur">

<INPUT TYPE="hidden" NAME="Paramètre" Valeur="Valeur">

<INPUT TYPE="hidden" NAME="Paramètre" Valeur="Valeur">

...

<INPUT TYPE="submit" Valeur="">

Exemple d'un appel POST de l'API dans l'interface HTML :

<FORM ACTION="http://geodiscover.cgdi.ca/gdp/[search]" METHOD="POST">

<INPUT TYPE="hidden" NAME="Action" Valeur=" searchForm ">

<INPUT TYPE="hidden" NAME="entryType" Valeur="productCollection">

<INPUT TYPE="hidden" NAME="displayHeader" Valeur="false">

<INPUT TYPE="hidden" NAME="language" Valeur="fr">

Le présent manuel définit des « modes » pour chacune des interfaces de l'interface HTML.

A3.2.5 Spécifier les paramétres

Il y a trois catégories de paramètres :

1. Obligatoire : Le paramètre doit toujours être précisé dans l'URL.
   
   
2. Conditionnel : Le paramètre pourrait être requis ou non, dépendant de la valeur que vous indiquez pour le paramètre nommé « request ».
   
   
3. Facultatif : Le paramètre peut être omis de l'URL. Certains paramètres facultatifs ont des valeurs par défaut qui s'appliquent lorsqu'un paramètre n'est pas précisé. Ceci est présenté en détail dans les pages suivantes.
   
   

Il n'est pas nécessaire de spécifier les paramétres pour chaque type.

L'API du Portail de découverte de GéoConnexions est conçue de telle façon qu'il n'est pas nécessaire d'inscrire les paramètres plus d'une fois dans une requête API. Si un paramètre est inscrit plus d'une fois, seulement la dernière spécification du paramètre sera utilisée.

Si vous spécifiez une combinaison de paramètres ou de valeurs qui est invalide, incomplète, incohérente, etc., vous recevrez soit une page d'erreur en HTML pour des interfaces HTML, soit une page d'erreur codée en XML pour des interfaces XML.

A3.2.6 Spécifications de l'API HTML

Cette sous-section présente les spécifications pour tous les paramètres dans l'API HTML. Pour connaître les paramètres à utiliser dans des demandes de services individuelles, veuillez consulter l'annexe A3.2.7, Définitions des paramètres de l'API HTML.

Les tableaux suivants énumèrent les différents paramètres que vous pouvez préciser, ainsi que les valeurs possibles pour chaque paramètre. Dans la plupart des cas, une valeur est une chaîne de caractères qui doit être précisée exactement de la façon indiquée. Toutefois, toutes les valeurs du tableau qui sont entre les parenthèses en chevron (<...>) peuvent varier, c.?à?d. que c'est à vous de les remplacer par le texte qui correspond à ce que vous voulez faire. Les sections suivantes définissent l'action de chacun de ces paramètres. L'ordre des paramètres dans l'URL n'a pas d'importance.

N'oubliez jamais d'insérer une perluète (&) entre chaque paire paramètre et que vous inscrivez dans une requête HTTP GET. Il faut noter que, si elles ne sont pas indiquées, certaines valeurs de paramètres auront des valeurs <par défaut>. Si l'URL est définie sans aucun paramètre, dans ce cas une aide en ligne détaillée est envoyée au navigateur de l'utilisateur.

Le paramètre action constitue la clé essentielle à toute fonction, étant donné qu'il détermine l'action qui sera exécutée et les autres paramètres qui doivent être inclus dans l'URL ainsi que leur signification.

Au fil du temps, d'autres services deviendront disponibles pour les API. Pour obtenir la liste des services disponibles pour les API HTML, veuillez consulter le guide API en ligne à l'adresse :

Il est également important de consulter cette URL pour se reporter à des listes valides (c.?à-d. des valeurs admissibles pour les paramètres) puisqu'elles peuvent changer.

A3.2.6.1 Paramètres communs à tous les modes

Toute requête API en HTML accepte les paramètres indiqués dans le tableau 8 :

A3.2.6.2 Afficher la page d'accueil

Ce mode affiche la page d'accueil.

Le mode index.jsp est utilisé pour cette requête (tel qu'exigé par l'interface HTML décrite à l'annexe A3.2.2, Forme et adresse URL d'un appel API GET dans l'interface HTML).

La présente section ne décrit que les spécifications de paramètres. La description des services et les définitions des paramètres sont présentées à l'annexe A3.2.7.1, Afficher la page d'accueil du Portail de découverte de GéoConnexions.

Aucun paramètre n'est exigé pour ce mode. Ce mode fait simplement afficher la page d'accueil du Portail de découverte de GéoConnexions sans faire apparaître la bannière du Portail de découverte de GéoConnexions en haut de la page.

Par exemple :

A3.2.6.3 Afficher des formulaires de recherche, des listes d'inscriptions, des résumés d'entrées

Ce mode fait afficher des formulaires de recherche, des listes d'entrées et des résumés d'inscriptions.

Le mode « search » est utilisé pour cette requête (tel qu'exigé par l'interface HTML décrite à l'annexe A3.2.2, Forme et adresse URL d'un appel API GET dans l'interface HTML).

Le tableau 9, Paramètres et valeurs pour l'affichage de formulaires de recherche, de listes d'entrées et de résumés d'inscriptions, ne présente que des spécifications de paramètres. Les descriptions de services et les définitions de paramètres sont présentées aux sections suivantes :

• Annexe A3.2.7.2, Afficher un service, une base de données ou une organisation en particulier;
  
  
• Annexe A3.2.7.3, Afficher la description d'un service, d'une base de données ou d'une organisation en particulier;
  
  
• Annexe A3.2.7.4, Effectuer une recherche dans des répertoires ou afficher un formulaire de recherche de produits (affichage seulement);
  
  
• Annexe A3.2.7.5, Afficher un formulaire de recherche de services;
  
  
• Annexe A3.2.7.6, Effectuer une recherche de services; et
  
  
• Annexe A3.2.7.7, Afficher un formulaire de recherche d'organisations.
  
  

Par exemple :

http://geodiscover.cgdi.ca/gdp/search?action=searchFoum& entryType=productCollection& displayHeader=false& language=fr

http://geodiscover.cgdi.ca/gdp/search?action=listEntries& entryType=service& selectionCriterion=c& numResultsPerPage=20& page=3& displayHeader=true& language=en

A3.2.6.4 Recherche de bases de données

Ce mode vous permet d'effectuer une recherche de bases de données. Il faut noter que product collection (collection de produits) est l'équivalent de database (base de données).

Le mode « search » est utilisé pour cette requête (tel qu'exigé par l'interface HTML décrite à l'annexe A3.2.2, Forme et adresse URL d'un appel API GET dans l'interface HTML).

Le tableau 10, Paramètres et valeurs pour la recherche de bases de données, présente les spécifications et les définitions des paramètres. Les descriptions des services sont disponibles à l'annexe A3.2.7.4, Effectuer une recherche dans des répertoires ou afficher un formulaire de recherche de produits.

Il faut noter que, pour le caractère « / », il faut utiliser la séquence d'échappement %2f dans les requêtes HTTP GET.

Par exemple :

A3.2.6.5 Recherche de services

Ce mode vous permet d'effectuer une recherche de services.

Le mode « search » est utilisé pour cette requête (tel qu'exigé par l'interface HTML décrite à l'annexe A2.3.2, Forme et adresse URL d'un appel API GET).

Le tableau 11, Paramètres et valeurs pour la recherche de services, présente des spécifications et des définitions de paramètres. Les descriptions des services sont présentées à l'annexe A3.2.7.6, Exécuter une recherche de services.

Par exemple :

A3.2.6.6 Recherche d'organisations

Ce mode vous permet d'effectuer une recherche d'organisations.

Le mode « search » est utilisé pour cette requête (tel qu'exigé par l'interface HTML décrite à l'annexe A3.2.2, Forme et adresse URL d'un appel API GET).

Le tableau 12, Paramètres et valeurs pour la recherche d'organisations, présente des spécifications et des définitions de paramètres. Les descriptions de services sont présentées à l'annexe A3.2.7.8, A3.2.7.8 Exécuter une recherche d'organisations.

Par exemple :

A3.2.7 Définitions des paramètres de l'API HTML

La présente section décrit la façon d'utiliser les paramètres pour chacune des demandes de services. Les demandes de services suivantes sont disponibles dans l'API HTML.

• A3.2.7.1 Affichage de la page d'accueil du Portail de découverte;
  
  
• A3.2.7.2 Affichage d'un service, d'une base de données ou d'une organisation en particulier;
  
  
• A3.2.7.3 Affichage de la description d'un service, d'une base de données ou d'une organisation en particulier;
  
  
• A3.2.7.4 Exécution d'une recherche dans un répertoire;
  
  
• A3.2.7.5 Affichage d'un formulaire de services ;
  
  
• A3.2.7.6 Exécution d'une recherche de services;
  
  
• A3.2.7.7 Affichage d'un formulaire de recherche d'organisations;
  
  
• A3.2.7.8 Exécution d'une recherche d'organisations;
  
  
• A3.2.7.9 Recherche d'un produit individuel dans une base de données reliée à Internet;
  
  
• A3.2.7.10 Affichage des entrées qu'un utilisateur possède ou qu'il peut modifier; et
  
  
• A3.2.7.11 Affichage de l'interface d'inscription (publicité) pour mettre à jour la publicité d'un service, d'une base de données ou d'une organisation.
  
  

A3.2.7.1 Afficher la page d'accueil du Portail de découverte de GéoConnexions

Le tableau 13, Paramètres et valeurs de l'API HTML pour l'affichage de la page d'accueil du Portail de découverte de GéoConnexions, indique les paramètres que vous devez préciser pour l'affichage de la page d'accueil du Portail de découverte de GéoConnexions :

Le mode « index.jsp » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodecouverte.icdg.ca/gdp/index.jsp?language=fr).

Dans l'exemple suivant, l'URL permet d'afficher en anglais la page d'accueil du Portail de découverte de GéoConnexions, sans la bannière de la page :

A3.2.7.2 Afficher un service, une base de données ou une organisation en particulier

Le tableau 14, Paramètres et valeurs pour l'affichage d'un service, d'une base de données ou d'une organisation en particulier, présente les paramètres que vous devez préciser en vue de l'affichage d'un service, d'une base de données ou d'une organisation en particulier, ainsi que la signification de chacune des valeurs

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet d'afficher en anglais une liste de tous les services décrits dans le répertoire :

A3.2.7.3 Afficher la description d'un service, d'une base de données ou d'une organisation en particulier

Le tableau 15, Paramètres et valeurs pour afficher la description d'un service, d'une base de données ou d'une organisation en particulier, indique les paramètres que vous devez préciser pour faire afficher la description d'un service, d'une base de données ou d'une organisation en particulier, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet d'afficher la description d'une base de données. Comme aucun paramètre ne précise la langue à utiliser, par défaut la liste s'affiche en anglais.

http://geodiscover.cgdi.ca/gdp/search?action=fullMetadata& entryType=productCollection& entryId=5136& entryLang=en& displayHeader=true& language=en

A3.2.7.4 Effectuer une recherche dans des répertoires ou afficher un formulaire de recherche de produits

Une recherche dans un répertoire vous permet de chercher des bases de données et des organisations qui vous intéressent dans le répertoire central. L'API Web offre deux interfaces pour la fonction de recherche dans le répertoire du système :

1. L'affichage d'un formulaire « Recherche de collections de produits » (où une collection de produits est l'équivalent d'une base de données) présente des critéres spécifiques de recherche. Ce formulaire permet à l'utilisateur final de modifier les paramètres de recherche prédéfinis, puis de soumettre le formulaire pour exécuter la recherche.

2. L'exécution d'une « Recherche de collections de produits » (où une collection de produits est l'équivalent d'une base de données) utilise des critéres spécifiques de recherche et affiche les résultats de cette recherche. Cette interface n'offre pas la possibilité à l'utilisateur de modifier les paramètres de recherche; seuls les résultats de la recherche définie sont affichés.

Le tableau 16, Paramètres et valeurs pour effectuer une recherche dans un répertoire ou afficher un formulaire de recherche de produits, indique les paramètres que vous devez préciser pour effectuer la recherche d'une base de données (collection de produits) dans un répertoire, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

A3.2.7.5 Afficher un formulaire de recherche de services

Une recherche dans un répertoire vous permet de chercher les services qui vous intéressent dans le répertoire central. L'API Web offre une interface permettant l'affichage du formulaire de recherche de services.

Le tableau 17, Paramètres et valeurs pour afficher le formulaire de recherche de services, indique les paramètres que vous devez préciser pour faire afficher le formulaire de recherche de services, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet d'afficher en anglais le formulaire « Recherche de collections de produits » ("collections de produits" = "base de données") contenant les valeurs indiquées dans les champs de critéres spatial et temporel :

http://geodiscover.cgdi.ca/gdp/search?action=searchForm&entryType=productCollection&language=fr&formType=advanced&location=%28-69+64+48+45%29%2FnorthAmerica%2Fcanada%2FnewBrunswick&locationName=%2FnorthAmerica%2Fcanada%2FnewBrunswick&northbc=48&westbc=-69&eastbc=64&southbc=45&chkIncludePlaceName=true&chkIncludeCoords=true&chkAllowOverlap=true&chkAllowGlobal=true&%20subject=subject%2FatmosphereWeather%2Fwinds&%20keywords=&date=All&fromMonth=&fromDay=&%20fromYear=&toMonth=&toDay=&toYear=&%20CurrentYear=2003&CurrentMonth=10&CurrentDay=14&%20productType=productType%2FallProductTypes&sortBy=placename

Lorsque vous changez l'action « searchForm » par « executeSearch », la recherche est exécutée et les résultats sont affichés.

Dans l'exemple suivant, l'URL permet d'afficher un formulaire de recherche en français :

http://geodiscover.cgdi.ca/gdp/search?action=searchForm&entryType=service&language=fr

A3.2.7.6 Exécuter une recherche de services

Une recherche dans un répertoire vous permet de chercher les services qui vous intéressent dans le répertoire central. L'API Web offre une interface permettant d'exécuter une recherche de services donnée.

Le tableau 18, Paramètres et valeurs pour exécuter une recherche de services, indique les paramètres que vous devez préciser pour exécuter une recherche de services, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet l'exécution d'une recherche de produits logiciels dans le domaine géospatial :

http://geodiscover.cgdi.ca/gdp/search?action=executeSearch &entryType=service& serviceType=SoftwareProducts& numResultsPerPage=25&page=3

A3.2.7.7 Afficher un formulaire de recherche d'organisations

Une recherche dans un répertoire vous permet de chercher des organisations qui vous intéressent dans le répertoire central. L'API Web offre une interface permettant d'afficher le formulaire de recherche d'organisations.

Le tableau 19, Paramètres et valeurs pour afficher le formulaire de recherche d'organisations, indique les paramètres que vous devez préciser pour afficher le formulaire de recherche d'organisations, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet d'afficher en français le formulaire de recherche d'organisations :

http://geodiscover.cgdi.ca/gdp/search?action=searchForm&entryType=organization&language=fr

A3.2.7.8 Exécuter une recherche d'organisations

Une recherche dans un répertoire vous permet de chercher les organisations qui vous intéressent dans le répertoire central. L'API Web offre une interface permettant d'exécuter une recherche d'organisations spécifique.

Le tableau 20, Paramètres et valeurs pour exécuter une recherche d'organisations, indique les paramètres que vous devez préciser pour exécuter une recherche d'organisations, ainsi que la signification de chacune des valeurs.

Le mode « search » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit :
http://geodiscover.cgdi.ca/gdp/search).

Dans l'exemple suivant, l'URL permet d'exécuter une recherche d'organisations liées au domaine géospatial au sein du gouvernement provincial du Nouveau-Brunswick :

http://geodiscover.cgdi.ca/gdp/search?action=executeSearch& entryType=organization& language=en& ougType=newBrunswick

Dans l'exemple suivant, l'URL permet d'exécuter une recherche de tous les types d'organisations liées au domaine géospatial et situées au Nouveau-Brunswick :

http://geodiscover.cgdi.ca/gdp/search?action=executeSearch& entryType=organization& language=en& location=newBrunswick

A3.2.7.9 Rechercher un produit individuel dans une base de données
reliée à Internet

Cette interface sera disponible plus tard. Lorsque ce service sera offert, il sera documenté dans les « pages d'aide » du Portail de découverte de GéoConnexions à l'adresse : http://geodiscover.cgdi.ca/gdp/about/en/6.4.html.

A3.2.7.10 Afficher les entrées qu'un utilisateur possède ou qu'il peut modifier

Le tableau 21, Paramètres et valeurs pour afficher les entrées qu'un utilisateur possède ou qu'il peut modifier, indique les paramètres que vous devez préciser pour afficher le résumé des inscriptions de l'utilisateur dans le Portail de découverte de GéoConnexions.

Le mode « advertising » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/advertising).

Dans l'exemple suivant, l'URL permet d'afficher le contenu du résumé propre à un utilisateur après son authentification :

http://geodiscover.cgdi.ca/gdp/advertising?entryType=productCollection& language=fr& displayHeader=false

Si l'utilisateur n'est pas déjà inscrit, le système d'authentification du Portail de découverte de GéoConnexions intercepte la requête avant que la page du résumé des entrées ne s'affiche et demande à l'utilisateur de s'identifier.

Après l'authentification de l'utilisateur, celui-ci recevra un résumé de ses entrées dans le Portail de découverte de GéoConnexions.

A3.2.7.11 Afficher l'interface d'inscription (pour mettre à jour l'entrée d'un service, d'une base de données ou d'une organisation)

Le tableau 22, Paramètres et valeurs pour afficher l'interface d'inscription (pour mettre à jour l'entrée d'un service, d'une base de données ou d'une organisation), indique les paramètres que vous devez préciser pour faire afficher l'interface de publicité, ainsi que la signification de chacune des valeurs.

Le mode « advertising » est utilisé pour cette requête HTML (ainsi l'URL se présente comme suit : http://geodiscover.cgdi.ca/gdp/advertising).

Dans l'exemple suivant, l'URL affiche une page de mise à jour d'une publicité :

http://geodiscover.cgdi.ca/gdp/advertising?action=edit& entryType=productCollection& entryLang=en& entryId=5136& language=en& displayHeader=false

Vous pouvez utiliser cette interface pour permettre à l'utilisateur d'appeler une opération de suppression.

Si l'utilisateur n'est pas déjà identifié, le système d'authentification du Portail de découverte de GéoConnexions intercepte la requête avant que la page d'édition des entrées ne s'affiche et demande à l'utilisateur de s'identifier.

Après l'authentification de l'utilisateur, celui-ci pourra modifier l'entrée.

Toutefois, si l'utilisateur n'est pas propriétaire ou éditeur de l'entrée qu'il tente de modifier, il ne pourra pas sauvegarder les modifications de l'entrée. L'utilisateur peut cependant sauvegarder une copie de l'entrée (et de tous les changements qu'il aura apportés) sous forme d'une nouvelle entrée dont il est propriétaire.