Web Services API de gestion des versions

Je vous propose un petit API de Services Web pour mes clients à qui j'ai l'intention d'évoluer au fil du temps. J'ai donc besoin d'une sorte de contrôle de version, mais je ne trouve pas de renseignements sur la façon de faire quelque chose comme ça.

Est-il une meilleure pratique?

Comment puis-je continuer à ajouter de nouvelles fonctionnalités sans casser la compatibilité avec les services web les consommateurs?

OriginalL'auteur Paul Izzy | 2009-11-05

  1. 19

    La gestion des versions est un sujet complexe, tout d'abord, vous devez définir vos objectifs en plus de manière descriptive. Il serait bien de dire que vous disposez d'une interface assure que vous ne serez jamais à casser la compatibilité, mais en fonction de ce que la nouvelle fonctionnalité est, qui pourrait même ne pas être possible. Donc, il y a différentes situations et différents arbitrages.

    Si votre intention est de ne fournir de nouvelles fonctionnalités à de nouveaux consommateurs, et l'ensemble de vos consommateurs sont des consommateurs directs (pas d'intermédiaires, cadres, etc.), puis un discret point de terminaison approche est le meilleur choix. Chaque fois que vous ajoutez une fonctionnalité que les risques d'une pause, de créer un nouveau point de terminaison, de lui donner un nouveau numéro de version, puis laissez-le savoir à des consommateurs pour la validation et passer leurs configurations. Cette stratégie est assez essayé et vrai, mais il a les inconvénients de mettre le fardeau sur les consommateurs à tenir à jour. Aussi, si il y a des dépendances entre les services, il peut devenir une corvée à suivre. L'avantage d'être si le code se casse, elle n'est pas (directement) de votre faute.

    L'autre principal de la stratégie est l'interface extensible. Il y a trois variétés différentes ici que je suis au courant. Tout d'abord, est le type de l'interface qui essaie de si bien décrire le domaine du service que chaque fonctionnalité que vous pouvez ajouter est en quelque sorte possible, compte tenu de l'interface existante. Si cela vous semble difficile, il est. On pourrait appeler cela l'interface parfaite. Tout est complètement décrit, mais l'ensemble du domaine est également complètement décrit. Le "parfait" n'est en réalité que sur le papier.

    La deuxième variété est le type qui ressemble à celle de l'interface normale, mais ajouter un générique de points d'extension. Dans le langage wsdl cela signifie xs:tout, des paires nom-valeur ou quelque chose de similaire. On pourrait appeler cela la base de l'interface extensible. Il n'est pas trop dur à faire, mais ce n'est pas sans complications. Les points d'extension peut rendre l'interface plus difficile de travailler avec, dans certains outillage (xs:tout), ou explicitement perdre une partie de votre capacité à valider les entrées et les sorties (les paires nom-valeur). Il est aussi assez facile à abuser de ces points d'extension d'une façon qui rend la version 3 ou 4 assez difficile à utiliser.

    La troisième variété est le type qui convertit votre interface dans un octet-stream. Vous pourriez appeler ces dieu interfaces. Ils ne sont pas sans leurs justifications, mais si vous en utilisez un, vous voulez vous demander pourquoi vous êtes à l'aide de services web. Peut-être vous devriez penser à raw TCP/IP ou HTTP GET/POST. Mais peut-être que vous avez marre de la complexité de fichiers wsdl et XSDs et vous voulez juste de commencer à partir de zéro, mais vous êtes lié à web-services pour des infrastructures de la raison. Réaliser cependant qu'une fois que vous commencez en bas de ce chemin, vous allez avoir besoin d'une toute nouvelle façon de décrire à vos consommateurs comment/ne pas utiliser votre service, et si vous utilisez XSD pour ça. eh bien, vous êtes essentiellement de retour où vous avez commencé.

    Votre meilleur pari est de savoir toutes ces options et l'approche de votre service de la conception en essayant d'abord pour le "parfait" interface", puis d'abandonner et de l'ajout de génériques points d'extensibilité. En essayant de la conception de l'interface parfaite va vous forcer à apprendre des choses qui feront de votre service mieux, pas seulement de votre interface, mais il faudra du temps, et si vous n'avez pas de limite de temps d'une certaine façon, ça va prendre une éternité.

    Un peu à court d'un vrai dieu de l'interface, il est l'interface de wrapper. Si vous êtes à la système de couches, vous voulez que votre interface en couches trop. Lorsque vous changez la couche B, vous voulez seulement changer la couche B, pas de toutes les instances dans la couche C.

    tous un peu abstrait, et la tarte dans le ciel à mon goût.
    Exactement comment est-il censé être le plus spécifique étant donné les renseignements fournis dans la question d'origine?

    OriginalL'auteur

  2. 8

    La stratégie la plus commune que j'ai vu est à la version du WSDL en ajoutant de la gestion des versions d'identification (généralement yyyy/MM[/dd]) à l'espace de noms d'objets dans le fichier wsdl, à savoir:

    targetNamespace="http://schemas.mycompany.com/2010/01/widgets"

    Cela peut être fait soit autype (types/schema) au niveau ou à l'ensemble du WSDL niveau - <definitions> en 1.1 ou <description> en 2.0.

    Un peu datée, mais ce lien d'IBM Développeur Travaille fournit la justification de cette approche, et en particulier lorsque les versions doivent être incrémenté:

    En arrière version compatible /non-dernières modifications:

    • L'ajout de nouvelles opérations
    • L'ajout de nouveaux types de

    Dernières modifications:

    • Supprimer ou renommer des opérations
    • La modification des paramètres à une méthode
    • La modification d'un type complexe

    OriginalL'auteur StuartLC

  3. 3

    J'ajoute généralement la chaîne de version de l'URL du service web, ce qui me donne "versionné points de terminaison". Le code de la mise en œuvre de ces points de terminaison peut être partagé, si les différences sont insignifiantes et peuvent être traitées par le même code ou le code peut être cloné, ou quelque part entre les deux.

    Les différents versionnées points de terminaison peut également utiliser de version de Schémas XML, si c'est ce que vous avez besoin.

    OriginalL'auteur skaffman

  4. 1

    Ajouter l'API "numéro de version" comme paramètre dans toutes vos API est ensuite mise en œuvre de la stratégie de modèle de votre site web code de service où le numéro de version dicte ce que la stratégie à utiliser.

    Cela ne peut fonctionner que si la version web services exactement les mêmes arguments, les mêmes WSDL s'applique. Si, dans une nouvelle version nécessite l'ajout d'un nouvel attribut que faites-vous?

    OriginalL'auteur ian

  5. 1

    L'une des possibilités est de la conception de toutes les opérations du service web n'avoir qu'un seul paramètre d'un type qui hérite de certains type abstrait qui contient le numéro de version. Cette approche est mise en œuvre par eBay web de la plate-forme de services.
    Quelque chose comme ce qui suit:

    <xsd:complexType name="AbstractRequestType">
  <xsd:attribute name="version" type="string" />
  ....

<xsd:complexType name="AddCustomerRequestType">
  <xsd:complexContent>
   <xsd:extension base="AbstractRequestType">
   ....

then use AddCustomerRequestType as a type of only parameter 
in addCustomer web service operation.

    De plus, si vous travaillez sur http, vous pouvez avoir besoin d'ajouter une version http GET paramètre de service web url de point de terminaison, de sorte que vous serez en mesure de détecter la version demandée facilement
    http://server/service?version=1

    OriginalL'auteur Gennady Shumakher