Contents
1. La présente norme recommande le style architectural REST comme approche à préférer en matière de conception d’API. Les architectures RESTful sont généralement plus simples à concevoir, à développer et à intégrer que les architectures SOAP. Ces dernières sont traitées ici dans un souci d’exhaustivité; on ne fournit pas d’exemple ni de cas d’utilisation.
2. Une API Web SOAP est une application logicielle identifiée par un URI, dont les interfaces et associations peuvent être définies, décrites et découvertes par des objets XML. De plus, elle prend en charge les interactions directes avec d’autres applications logicielles utilisant des messages en XML par l’intermédiaire de protocoles Internet tels que SOAP et HTTP.
3. Un contrat basé sur SOAP est décrit dans un langage de description de services Web (WSDL), qui est un document type élaboré par le W3C. D’un bout à l’autre du présent document, le “document WSDL valant contrat de service Web” sera simplement désigné par l’abréviation “WSDL”.
4. Deux styles peuvent présider à la création de services Web : le contrat en dernier et le contrat en premier. Selon l’approche du contrat en dernier, on commence par le code, et le contrat de services Web est généré en conséquence. Avec l’approche du contrat en premier, on commence par le contrat WSDL et on utilise le code pour exécuter ledit contrat.
5. Le profil du Web Service Interoperability (interopérabilité des services Web) (WS-I) est l’une des normes les plus importantes en matière d’API basées sur SOAP, et il fournit un socle minimal à l’écriture de services Web capables de travailler ensemble. Il donne des orientations sur la manière dont les services sont “exposés” les uns aux autres et sur leur mode de transfert d’informations (ou “messagerie”). Ce profil sert à exécuter des versions spécifiques de certaines des plus importantes normes applicables aux services Web, à savoir notamment WSDL, SOAP et XML. Le fait de se conformer à certains profils implique une conformité à des versions spécifiques de ces normes. WS-I Basic Profile v1.1 donne des conseils pour utiliser XML 1.0, HTTP 1.1, UDDI, SOAP 1.1, WSDL 1.1 et UDDI 2.0. WS-I Basic Profile 2.0 donne des conseils pour utiliser SOAP 1.2, WSDL 1.1, UDDI 2.0, WS-Addressing et MTOM. SOAP 1.2 fournit un modèle de traitement clair et améliore l’interopérabilité. WSDL 2.0 a été mis au point pour résoudre les problèmes d’interopérabilité que présentait WSDL 1.1 en utilisant des associations SOAP 1.2 améliorées.
[WS-01] Tous les WSDL DOIVENT se conformer au WS-I Basic Profile 2.0. Le WSDL 1.2 PEUT être utilisé.
6. Une association WSDL SOAP peut être une association de style d’appel de procédure à distance (RPC) ou une association de style de document. Une association SOAP peut également avoir une utilisation codée ou une utilisation littérale. On a ainsi cinq styles/modèles d’utilisation : RPC/codé, RPC/littéral, document/codé, document/littéral, document/littéral compacté.
[WS-02] Les services DOIVENT suivre l’association de style de document et les modèles d’utilisation littérale (document/littéral ou document/littéral compacté). Lorsqu’il y a des graphiques, le style RPC/code DOIT être utilisé.
[WS-03] Pour les cas d’utilisation exceptionnels, par exemple en cas d’opérations surchargées dans le WSDL, tous les autres styles DEVRAIENT être utilisés.
7. Le WSDL concret devrait être séparé du WSDL abstrait afin de fournir une interface plus modulaire et flexible. Le WSDL abstrait définit les types de données, les messages, l’opération et le type de port. Le WSDL concret définit l’association, le port et le service.
[WS-04] Le WSDL DEVRAIT être divisé en une partie abstraite et une partie concrète.
[WS-05] Tous les types de données DEVRAIENT être définis dans un fichier XSD et importés dans le WSDL abstrait.
[WS-06] Le WSDL concret ne DOIT définir qu’un seul service avec un seul port.
8. Les schémas utilisés dans le WSDL doivent être conformes à la norme ST.96 de l’OMPI. À des fins de réutilisation et dans l’optique de la modularité, un schéma doit être un document distinct qui est soit inclus, soit importé dans le WSDL, au lieu d’être défini directement dans ce dernier. Il sera alors possible de modifier la structure XML sans modifier le WSDL.
[WS-07] Le schéma défini dans l’élément wsdl:types DOIT être importé d’un fichier de schéma autonome, pour permettre la modularité et la réutilisation.
[WS-08] L’importation d’un schéma externe DOIT être implémentée à l’aide d’une technique xsd:import, et non une xsd:include.
[WS-09] L’élément xsd:any NE DOIT PAS être utilisé pour spécifier un élément racine dans le corps du message.
[WS-10] L’espace de nommage cible pour le WSDL (attribut targetNamespace sur wsdl:definitions) DOIT être différent de l’espace de nommage cible du schéma (attribut targetNamespace sur xsd:schema).
[WS-11] Les requêtes et les réponses (convention de nommage, format de message, structure des données et dictionnaire de données) DEVRAIENT suivre la norme ST.96 de l’OMPI.
9. Des conventions de nommage appropriées devraient également être appliquées pour nommer les services et les éléments de WSDL. Ces conventions de nommage devraient suivre celles qui sont implémentées dans la norme ST.96 de l’OMPI.
[WS-12] Les services DOIVENT être nommés en caractères haut de casse de type “camel” et avoir un suffixe “Service”, par exemple https://wipo.int/PatentsService.
[WS-13] Les éléments WSDL que sont le message, la partie, le type de port, l’opération, les données d’entrée, les données de sortie et l’association DEVRAIENT être nommés en caractères haut de casse de type “camel”.
[WS-14] Les noms des messages de requête DEVRAIENT avoir un suffixe “Request”.
[WS-15] Les noms des messages de réponse DEVRAIENT avoir un suffixe “Response”.
[WS-16] Les noms d’opération DEVRAIENT suivre le format <Verb><Object>{<Qualifier>}, où <Verb> indique l’opération (de préférence Get, Create, Update ou Delete, le cas échéant) sur l’<Object> de l’opération, éventuellement suivie d’un <Qualifier> de l’<Object>.
10. Tous les noms d’opération auront au moins deux parties. Une troisième partie facultative peut être incluse pour clarifier ou préciser le but de l’opération. Les trois parties sont : <Verb> <Object> <Qualifier – Optional>. Chaque partie est décrite en détail ci-après.
Verbe – chaque nom d’opération commencera par un verbe. On trouvera ci-après des exemples de verbes couramment utilisés.
|
Verbe |
Description |
Exemple |
|
Get |
Extraire un objet unique |
GetBibData |
|
Create |
Extraire un nouvel objet |
CreateBibData |
|
Update |
Mettre à jour un objet |
UpdateBibData |
|
Delete |
Supprimer un objet |
DeleteCustomer |
Objet – Un nom suivant un verbe sera une description succincte et non ambiguë de la fonction de l’opération. Il s’agit de donner sans ambiguïté aux consommateurs une meilleure idée de ce qu’accomplit l’opération. Étant donné que les différents centres de coût ne définissent pas certaines entités de la même manière, l’objet peut être un champ composite dont le premier nœud est le centre de coût et le deuxième l’entité, par exemple PatentCustomer.
– L’attribut (facultatif) qualificatif de l’objet a pour objectif de préciser davantage le domaine d’activité.