Salut! En tant que fournisseur API (ingrédient pharmaceutique actif), on me demande souvent ce qu'est un schéma API. Donc, je pensais que je prendrais le temps de le décomposer pour vous d'une manière facile à comprendre.
Commençons par les bases. Un schéma API est comme un plan pour une API. Il s'agit d'une description détaillée du fonctionnement d'une API, des données qu'il attend et des données qu'il renvoie. Considérez-le comme un ensemble de règles et de directives que le fournisseur d'API (c'est moi!) Et le consommateur API (c'est vous ou votre équipe) devez suivre pour assurer une communication fluide et efficace.
Pourquoi un schéma API est-il important?
Eh bien, imaginez que vous construisez une maison. Vous ne commenceriez pas simplement à jeter des briques sans plan, non? Il en va de même pour les API. Un schéma API fournit un moyen clair et cohérent pour les développeurs de comprendre et d'utiliser l'API. Il aide à éviter les malentendus, réduit les chances d'erreurs et facilite l'intégration de l'API dans différentes applications.
Par exemple, disons que vous êtes un développeur qui cherche à utiliser notre API pour accéder aux informations surNiobium nano-carbonisé, carbure de niobium micron, carbure de niobium ultra-fin, HFC. Le schéma API vous dira exactement quels points de terminaison sont disponibles, quels paramètres vous devez passer et dans quel format la réponse sera.
Qu'y a-t-il dans un schéma API?
Un schéma API comprend généralement les composants suivants:
1. Points de terminaison
Ce sont les URL que vous pouvez appeler pour accéder aux fonctionnalités de l'API. Chaque point de terminaison représente une opération spécifique, comme l'obtention d'une liste de produits, la création d'une nouvelle commande ou la mise à jour des informations utilisateur.
2. Formats de demande et de réponse
Le schéma définira le format des données que vous devez envoyer dans vos demandes (par exemple, JSON, XML) et le format des données que l'API renverra dans ses réponses. Cela garantit que le fournisseur d'API et le consommateur sont sur la même longueur d'onde en ce qui concerne la gestion des données.
3. Paramètres
Ce sont les valeurs que vous pouvez transmettre à un point final pour personnaliser l'opération. Par exemple, vous pouvez transmettre un ID de produit pour obtenir des informations sur un produit spécifique, ou une plage de dates pour filtrer une liste de commandes.
4. Gestion des erreurs
Le schéma décrira également comment l'API gérera les erreurs. Il définira les codes d'erreur que l'API pourrait renvoyer et ce que chaque code signifie. Cela aide les développeurs à comprendre ce qui s'est mal passé lorsqu'une erreur se produit et comment le réparer.
Types de schémas API
Il existe plusieurs types de schémas API, chacun avec ses propres avantages et cas d'utilisation. Certains des plus courants comprennent:
Spécification OpenAPI (OEA)
C'est l'une des normes les plus populaires pour documenter les API RESTful. Il utilise un fichier YAML ou JSON pour décrire les points de terminaison de l'API, les formats de demande et de réponse, les paramètres, etc. OAS est largement pris en charge par des outils et des cadres, ce qui facilite la génération de documentation, de SDK et de cas de test.
Schéma GraphQL
GraphQL est un langage de requête pour les API qui permet aux clients de demander exactement les données dont ils ont besoin. Un schéma GraphQL définit les types de données que l'API peut renvoyer et les opérations qui peuvent être effectuées sur ces types. Il fournit un moyen plus flexible et efficace d'accéder aux données par rapport aux API RESTful traditionnelles.
Tampons de protocole
Les tampons de protocole (Protobuf) sont un format de sérialisation binaire agnostique en langue développé par Google. Il utilise un fichier de schéma pour définir la structure des données qui seront sérialisées et désérialisées. Protobuf est connu pour ses performances élevées et sa petite taille de message, ce qui en fait un choix populaire pour les API qui doivent gérer de grandes quantités de données.
Comment nous utilisons les schémas API comme fournisseur d'API
En tant que fournisseur d'API, nous comptons sur des schémas API pour nous assurer que nos API sont faciles à utiliser et à intégrer. Nous utilisons la spécification OpenAPI pour documenter nos API, ce qui nous permet de fournir une documentation claire et détaillée pour nos clients. Cette documentation comprend des informations sur les points de terminaison, les formats de demande et de réponse, les paramètres et la gestion des erreurs.
Nous utilisons également des schémas API pour valider les demandes que nous recevons de nos clients. En vérifiant les demandes entrantes contre le schéma, nous pouvons nous assurer que les données sont dans le bon format et que tous les paramètres requis sont présents. Cela aide à prévenir les erreurs et garantit que nos API sont fiables et sécurisées.
De plus, nous utilisons des schémas API pour générer des SDK et des cas de test. En utilisant des outils qui prennent en charge la spécification OpenAPI, nous pouvons générer automatiquement du code dans différents langages de programmation, ce qui permet à nos clients d'intégrer plus facilement nos API dans leurs applications. Nous utilisons également le schéma pour générer des cas de test, ce qui nous aide à nous assurer que nos API fonctionnent correctement et qu'ils répondent aux exigences de nos clients.
Exemples du monde réel
Jetons un coup d'œil à quelques exemples du monde réel de la façon dont les schémas API sont utilisés.
Exemple 1: utiliser notre API pour obtenir des informations surThioxanthen-9-one CAS de haute qualité: 492-22-8
Supposons que vous soyez un chercheur qui cherche à obtenir des informations sur un composé chimique spécifique. Vous pouvez utiliser notre API pour accéder aux données telles que les propriétés du composé, les méthodes de synthèse et les informations de sécurité. Le schéma API vous dira exactement quel point de terminaison appeler, quels paramètres passer (par exemple, le numéro CAS) et dans quel format la réponse sera dans.
Voici un exemple de demande à notre API en utilisant Curl:
curl -x get "https://api.oursite.com/compounds/492-22-8" -h "accepter: application / json"La réponse peut ressembler à ceci:
{"Name": "thioxanthen-9-one", "Cas_number": "492-22-8", "moléculaire_onde": 212.26, "Propriétés": {"Melting_point": "85-87 ° C", "Boiling_Point": "365.7 ° C à 760 mmhg"}, "Sythissis_methods": "Method 1:" React x avec y en présence de z ... "," Méthode 2: Utilisez les conditions de réaction suivantes ... "]}Exemple 2: Création d'une nouvelle commande pourCAS n ° 455943-61-0 grande approvisionnement
Si vous êtes une entreprise pharmaceutique qui cherche à passer une commande pour une grande fourniture d'une API spécifique, vous pouvez utiliser notre API pour créer une nouvelle commande. Le schéma API définira le point de terminaison pour créer une commande, le format de demande (par exemple, les détails de la commande, la quantité et l'adresse de livraison) et le format de réponse (par exemple, l'ID de commande et le message de confirmation).
Voici un exemple de demande à notre API à l'aide de Python:
Importer les demandes url = "https://api.oursite.com/orders" data = {"product_id": "455943-61-0", "Quantity": 1000, "Delivery_Address": "123 Main St, anytown, USA"} Headers = {"Content-Type": "application / json"} Réponse = remanie en-têtes = en-têtes) imprimer (réponse.json ())La réponse peut ressembler à ceci:
{"Order_id": "123456", "message": "Ordre créé avec succès. Votre commande sera traitée dans les 24 heures." }Conclusion
En conclusion, un schéma API est une partie cruciale de toute API. Il fournit un moyen clair et cohérent pour les développeurs de comprendre et d'utiliser l'API, réduit les chances d'erreurs et facilite l'intégration de l'API dans différentes applications. En tant que fournisseur d'API, nous comptons sur des schémas API pour nous assurer que nos API sont faciles à utiliser, fiables et sécurisées.
Si vous souhaitez utiliser nos API pour accéder à des informations sur nos produits ou pour passer des commandes, nous serions ravis de vous entendre. Que vous soyez un chercheur, une entreprise pharmaceutique ou un développeur, nos API peuvent vous fournir les données et les fonctionnalités dont vous avez besoin. Alors, n'hésitez pas à nous contacter pour discuter de vos besoins et commencer le processus d'approvisionnement. Nous sommes ici pour vous aider à tirer le meilleur parti de nos API et pour vous assurer que votre expérience avec nous est positive.
Références
- Fielding, RT (2000). Styles architecturaux et conception d'architectures logicielles basées sur le réseau. Université de Californie, Irvine.
- Khare, R. et Frystyk, H. (1997). Protocole de transfert hypertexte - HTTP / 1.1. RFC 2068.
- Lindley, S. et Miller, B. (2015). GraphQL: un langage de requête de données. Facebook.
- Varda, A. (2008). Tampons de protocole: format d'échange de données de Google. Blog open source Google.
