Cette page s'applique à Apigee et à Apigee hybrid.
Consultez la documentation d'Apigee Edge.
Dans la phase de conception, vous définissez les exigences de votre API. En tant que concepteur d'API, vous planifiez les services que vous souhaitez exposer aux consommateurs et concevez des API pour y accéder. Créez l'un des documents suivants pour capturer les exigences de votre API :
- Un document OpenAPI
- Un schéma GraphQL
Les sections suivantes fournissent des informations supplémentaires sur les documents OpenAPI et GraphQL, ainsi que sur leur rôle dans le cycle de vie de votre API. Pour comparer les deux options de conception des API, consultez la comparaison de REST et de GraphQL dans cet article de blog.
Qu'est-ce que la spécification OpenAPI ?
"L'OpenAPI Initiative (OAI) se concentre sur la création, l'évolution et la promotion d'un format de description d'API neutre du point de vue du fournisseur, basé sur la spécification Swagger." Pour en savoir plus sur l'OpenAPI Initiative, consultez le site https://openapis.org.
Un document OpenAPI utilise un format standard pour décrire une API RESTful. Développées au format JSON ou YAML, les documents OpenAPI sont lisibles par une machine, mais sont également faciles à lire et à comprendre pour les humains. La spécification OpenAPI permet une description formelle des éléments d'une API tels que son chemin de base, ses chemins et verbes, en-têtes, paramètres de requête, types de contenus, modèles de réponse, etc. En outre, un document OpenAPI est couramment utilisée pour générer la documentation de l'API.
Voici un fragment d'un document OpenAPI qui décrit l'exemple simple "Hello World" d'Apigee. Pour en savoir plus, consultez la spécification OpenAPI sur GitHub.
openapi: 3.0.0
info:
description: OpenAPI Specification for the Apigee mock target service endpoint.
version: 1.0.0
title: Mock Target API
paths:
/:
get:
summary: View personalized greeting
operationId: View a personalized greeting
description: View a personalized greeting for the specified or guest user.
parameters:
- name: user
in: query
description: Your user name.
required: false
schema:
type: string
responses:
"200":
description: Success
/help:
get:
summary: Get help
operationId: Get help
description: View help information about available resources in HTML format.
responses:
"200":
description: Success
...
Il existe un grand nombre d'excellentes sources d'informations sur les spécifications OpenAPI. Le site OpenAPI Initiative constitue un bon point de départ, où vous trouverez des présentations, des blogs et des liens vers la spécification OpenAPI. Consultez la spécification pour obtenir une description détaillée des éléments de schéma et des types de données.
Vous pouvez télécharger plusieurs exemples de documents OpenAPI JSON et YAML à partir du dépôt de spécifications OpenAPI.
Qu'est-ce qu'un schéma GraphQL ?
Un schéma GraphQL décrit les données disponibles dans votre API afin qu'un client puisse les interroger.
Voici les avantages qu'offre GraphQL :
- Un seul point de terminaison permet d'accéder à tous les champs pour une opération donnée.
- Le langage de requête puissant, appelé "Schema Definition Language" (Langage de définition de schéma), vous permet d'accéder directement aux données dont vous avez besoin, évitant ainsi la récupération superflue ou la sous-récupération des données.
- Le traitement des requêtes s'effectue en parallèle.
Pour en savoir plus sur GraphQL, consultez la page graphql.org.
Vous trouverez ci-dessous un exemple de schéma GraphQL qui définit le point d'entrée des données (type de requête), les opérations d'écriture disponibles (type de mutation) et les types de données.
type Query {
Greeting: String
students: [Student]
}
type Mutation {
createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
newStudent: Student!
}
type Student {
Id: ID!
firstName: String!
lastName: String!
password: String!
collegeId: String!
}
Vous pouvez interroger le schéma GraphQL pour renvoyer les données exactes dont vous avez besoin sous forme de charge utile JSON.
Que se passe-t-il si je modifie un document ?
Chaque document OpenAPI ou GraphQL sert de source d'information tout au long du cycle de vie de l'API. Le même document est utilisée à chaque phase du cycle de vie de l'API, du développement à la publication, en passant par la surveillance.
Lorsque vous modifiez ou supprimez un document, cela a un impact sur la ligne suivante :
- Si vous modifiez un document, vous devez modifier manuellement les artefacts associés, y compris le proxy d'API et tous les produits d'API qui exposent ses ressources, mais aussi générer de nouveau la documentation de référence de l'API pour refléter les modifications apportées au document.
- Si vous supprimez un document, vous devez supprimer manuellement les artefacts associés, y compris le proxy d'API, modifier les produits d'API pour supprimer les ressources associées, puis générer de nouveau la documentation de référence de l'API pour refléter la suppression du document et de ses ressources.
Que se passe-t-il lorsque je crée un proxy d'API à partir d'un document OpenAPI ?
Vous pouvez créer vos proxys d'API à partir de vos documents OpenAPI. En quelques clics, vous obtenez un proxy d'API avec les chemins, paramètres, flux conditionnels et points de terminaison cibles générés automatiquement. Vous pouvez ensuite ajouter des fonctionnalités telles que la sécurité OAuth, la limitation du débit et la mise en cache.
Vous pouvez créer un proxy d'API à partir d'un document OpenAPI à l'aide de l'assistant de création de proxy, comme décrit dans la section Utiliser des spécifications OpenAPI pour générer des proxys. Pour une expérience pratique, suivez les étapes de la section Créer un proxy d'API à partir d'une spécification OpenAPI.
Lorsque vous publiez votre API, vous prenez un instantané du document OpenAPI pour générer la documentation de référence de l'API. Cet instantané représente une révision spécifique du document de description.