<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
<!ENTITY config SYSTEM "configuration.xml" NDATA XML>
]>
<webpage id="api-url">
	<head>
		<title>Les changements à l'API-URL</title>
		<titleabbrev>API-URL</titleabbrev>
		<author>
			<firstname>Martin</firstname>
			<surname>Sévigny</surname>
			<affiliation>
				<orgname>AJLSM</orgname>
			</affiliation>
		</author>
		<author>
			<firstname>Frédéric</firstname>
			<surname> Glorieux</surname>
			<affiliation>
				<orgname>AJLSM</orgname>
			</affiliation>
		</author>
		<revhistory>
			<revision>
				<revnumber>1.0</revnumber>
				<date>2002/10/31</date>
			</revision>
		</revhistory>
	</head>
	<para>L'API-URL de SDX est utilisée pour appeler des services directement depuis un navigateur ou depuis tout environnement capable de récupérer du contenu depuis une URL. C'est le cas, notamment, d'un processeur XSLT grâce à la fonction <command>document()</command>, ce qui peut être utile pour compléter la présentation d'un document avec des informations annexes gérées par SDX.</para>
		<para>Pour une migration facile, <emphasis role="bold">les fonctions SDX-1 conservées réagissent aux mêmes paramètres, mais ces noms et paramètres sont dépréciés.</emphasis>.</para>
		<para>L'accès URL vise à être <emphasis>compatible</emphasis> avec l'API-XSP, en particulier, en utilisant les mêmes paramètres URL par défaut, en utilisant les mêmes noms de fonction. Ce document souligne essentiellement, les fonctions non supportées, les nouvelles normes pour les fonctions SDX-1. La documentation de référence de l'<emphasis role="bold">API-SDX</emphasis> définit toutes les fonctionnalités, en particulier celles ajoutées.</para>
		<para>L'URL de base est fournie dans chaque document SDX par un attribut (<sgmltag>api-url</sgmltag>) dans l'élément racine (<sgmltag>&lt;sdx:document xml:lang="fr-FR" server="{$server-url}" api-url="{$server-url}/sdx/api-url/" ... /&gt;</sgmltag>).</para>
	
	<section>
		<title>Les fonctions non supportées</title>
		<para>L'utilisation de l'une ou l'autre de ces fonctions génèrera une erreur car elles ne sont plus supportées par SDX-2.</para>
		<variablelist>
			<varlistentry>
				<term>user</term>
				<listitem>
					<para>Cette fonction est supprimée car elle peut causer des problèmes de sécurité et son utilité est plutôt restreinte.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>tabledata</term>
				<listitem>
					<para>Les tables associées ne sont plus supportées en SDX-2 et cette fonction n'est donc plus utile.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>html2xhtml</term>
				<listitem>
					<para>L'environnement Cocoon-2 permet de transformer un document HTML en format XHTML très simplement, à l'aide d'un <emphasis>pipeline</emphasis> dont la source est le document HTML et qui sérialisé avec le sérialiseur par défaut. Cette fonction spécifique à SDX n'est donc plus utile, le <emphasis>sitemap</emphasis> permet d'aller plus loin.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	<section>
		<title>Les fonctions modifiées</title>
		<para>Les modifications portent avant tout sur les paramètres, afin de les adapter à la nouvelle architecture de SDX-2 (plusieurs bases de documents par application, plusieurs entrepôts par bases de documents). Par ailleurs, l'unification du vocabulaire a déprécié certains noms.</para>
		<variablelist>
			<varlistentry>
				<term>executeSimpleQuery</term>
				<term>executeFieldQuery</term>
				<term>executeLinearQuery</term>
				<term>
					<emphasis>(simplesearch)</emphasis>
				</term>
				<term>
					<emphasis>(fieldsearch)</emphasis>
				</term>
				<term>
					<emphasis>(linearsearch)</emphasis>
				</term>
				<listitem>
					<para>Les anciens noms de requêtes sont supportés avec les anciens paramètres. Attention, ils sont dépréciés. Il est conseillé d'employer les noms de l'API-SDX (l'API-XSP). </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>app</term>
				<term>appbypath</term>
				<term>
					<emphasis>(db)</emphasis>
				</term>
				<listitem>
					<para> L'appel à l'API-URL se voulant générique et hors contexte, il faut au moins spécifier l'application concernée par la fonction. Le reste (base de documents, entrepôt) reçoit une valeur par défaut, ce qui est le cas général d'une application SDX-1 (avec une seule base cherchable par application). Le paramètre URL <emphasis role="bold">?app=fr.gouv.culture.sdx.sdxworld</emphasis> permet d'accéder à l'application sdxworld. Notez que le paramètre réagit à un identifiant d'application qui se veut "unique au monde" (selon le même format qu'une classe java, une sorte d'URL renversée). Ce code est un identifiant spécifié dans <filename>application.xconf</filename>. Cette convention permet à des applications sur différents serveurs de communiquer sans se confondre.  Par commodité le paramètre <emphasis>?appbypath=</emphasis> est supporté, il réagit au nom du répertoire sous le serveur SDX qui porte l'application (l'ancien "code de la base de documents"). Le paramètre URL <emphasis>?db=code</emphasis> est déprécié, il  ne fonctionne qu'avec les anciennes servlets SDX-1. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>query</term>
				<term>q</term>
				<term>field</term>
				<term>f</term>
				<term>value</term>
				<term>v</term>
				<term>op</term>
				<term>
					<emphasis>(o)</emphasis>
				</term>
				<listitem>
					<para>La formulation d'une requête de recherche peut se faire selon de nombreux types (simple, champ, linéaire ...), toutefois les paramètres nécessaires partagent une même logique. Le paramètre query est réservé uniquement à la recherche libre, en effet, la syntaxe permet par exemple des recherches sur un champ  <emphasis role="bold">executeSimpleQuery?query=sdxall:1</emphasis>. La différence avec SDX-1 ne se situe pas dans le nom du paramètre, la forme abrégée <emphasis role="bold">?q=</emphasis> fonctionne aussi, par contre, il n'est jamais utilisé en doublet avec un champ (?f=). La requête <emphasis role="bold">executeFieldQuery?app=fr.gouv.culture.sdx.sdxworld&amp;field=sdxall&amp;value=1</emphasis> est identique à la précédente, notez que field accepte la forme abrégée <emphasis role="bold">?f=</emphasis>, et value correspond à <emphasis role="bold">?v=</emphasis>. Pour une requête linéaire, on peut procéder ainsi <emphasis role="bold">executeLinearQuery?app=fr.gouv.culture.sdx.sdxworld &amp;f=sdxall&amp;v=1&amp;op=and&amp;f=contenu&amp;v=a*&amp;op=and</emphasis> (ce qui donnera sensiblement les mêmes résultats que les requêtes précédentes, puisqu'il y a toujours un champ sdxall égal à 1, et souvent un mot commençant par a, "a*", dans un champ plein texte). Vous aurez remarqué que la forme ?o= a été abandonnée, au profit de <emphasis role="bold">?op=</emphasis>. Toutefois, rappelons le, les requêtes de recherche conservées avec les anciens noms SDX-1 réagissent aux anciens paramètres.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>qid</term>
				<term>hpp</term>
				<term>page</term>
				<term>p</term>
				<term>
					<emphasis>(h)</emphasis>
				</term>
				<term>
					<emphasis>(n)</emphasis>
				</term>
				<listitem>
					<para>Les résultats de requête et les listes de termes demandent plusieurs informations pour être navigables page à page. D'abord, ces résultats doivent être identifiés pour être rappelés, c'est le rôle du paramètre  <emphasis role="bold">?qid=q5</emphasis>, valeur fournie par l'attribut <sgmltag>id</sgmltag> d'un élément <sgmltag>&lt;sdx:results/&gt;</sgmltag> ou <sgmltag>&lt;sdx:terms/&gt;</sgmltag>, (même fonction que l'ancien <emphasis>?n=</emphasis> ). On peut vouloir fixer le nombre de résultats par page (<emphasis role="bold">?hpp=100</emphasis>), afin de modifier la valeur par défaut qui est de 20 (même fonction que l'ancien <emphasis>?h=</emphasis>). Enfin, pour accéder à une page précise, le paramètre canonique est <emphasis role="bold">?page=10</emphasis>, toutefois il existe aussi une forme abrégée identique à l'ancien paramètre  (<emphasis role="bold">?p=10</emphasis>). </para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section><section><title>Conclusion</title>
		<para>En résumé, une migration rapide n'oblige pas à relire toutes les XSL qui appelerait l'ancienne API-URL. Toutefois, il est conseillé d'en repenser l'usage. Elle sera conservée comme une commodité générique, mais un développeur d'application aura tout intérêt à développer ses propres "servlets", afin d'économiser le nombre de paramètres à lui passer (pour spécifier l'application, la base...). Selon l'architecture Cocoon-2, il ne s'agit en fait que d'une page XSP, passant par la même transformation logique (la "logicsheet" <filename>sdx.xsl</filename>), et sérialisée en XML (pour être lisible depuis une XSL). Voyez par vous même <filename>{$server}/sdx/sitemap.xmap</filename>, <filename>{$server}/sdx/api-url/*.xsp</filename>, <filename>{$server}/sdx/api-url/api-url.xsl</filename>.</para>
	</section>
	
</webpage>
