Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
En la fase de diseño, debes definir los requisitos para tu API. Como diseñador de API, debes planificar los servicios que deseas exponer a los consumidores y diseñas API para acceder a esos servicios. Creas uno de los siguientes documentos para capturar los requisitos de tu API:
- Un documento de OpenAPI
- Un esquema de GraphQL
En las siguientes secciones, se proporciona más información sobre los documentos de OpenAPI y GraphQL y el rol que desempeñan en el ciclo de vida de tu API. Para ver una comparación de las dos opciones de diseño de la API, consulta la comparación de REST y GraphQL en esta entrada de blog.
¿Qué es la especificación de OpenAPI?
“Open API Initiative (OAI) se enfoca en crear, desarrollar y promocionar un formato de descripción de API que no dependa de los proveedores y esté basado en la especificación de Swagger”. Para obtener más información sobre OpenAPI Initiative, consulta https://openapis.org.
Un documento de OpenAPI usa un formato estándar para describir una API RESTful. Un documento de OpenAPI escrito en formato JSON o YAML es legible para las máquinas, pero también es fácil de leer y comprender para las personas. La especificación de OpenAPI permite la descripción formal de elementos de una API, como su ruta base, las rutas y verbos, los encabezados, los parámetros de consulta, los tipos de contenido, los modelos de respuesta y más. Además, un documento de OpenAPI se suele usar para generar documentación de la API.
Este es un fragmento de un documento de OpenAPI que describe la muestra de Hello World simple de Apigee. Para obtener más información, consulta la Especificación de OpenAPI en 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
...
Existen muchas fuentes excelentes de información sobre las especificaciones de OpenAPI. Recomendamos comenzar con el sitio OpenAPI Initiative, en el que encontrarás descripciones generales, blogs y vínculos a la Especificación de OpenAPI. Consulta la especificación para obtener descripciones detalladas de los elementos del esquema y los tipos de datos.
Hay varios documentos JSON y YAML de ejemplo de OpenAPI que puedes descargar desde el repositorio de especificaciones de OpenAPI.
¿Qué es un esquema de GraphQL?
Un esquema de GraphQL describe los datos disponibles en tu API para que los consulte un cliente.
Los beneficios de usar GraphQL incluyen los siguientes:
- Un solo extremo proporciona acceso a todos los campos para una operación determinada
- El potente lenguaje de consulta, llamado Lenguaje de definición de esquemas, te permite acceder de forma exacta a los datos que necesitas, lo que evita la recuperación excesiva o insuficiente de datos.
- El procesamiento de consultas se realiza en paralelo
Para obtener más información sobre GraphQL, consulta graphql.org.
A continuación, se proporciona un ejemplo de un esquema GraphQL que define el punto de entrada de datos (tipo de consulta), las operaciones de escritura disponibles (tipo de mutación) y los tipos de datos.
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!
}
Puedes consultar el esquema GraphQL para mostrar los datos exactos que necesitas como carga útil de JSON.
¿Qué sucede si modifico un documento?
Cada documento de OpenAPI o GraphQL sirve como fuente de información confiable a lo largo del ciclo de vida de la API. Se usa el mismo documento en cada fase del ciclo de vida de la API, desde el desarrollo hasta la publicación y la supervisión.
Cuando editas o borras un documento, afecta la siguiente línea:
- Si editas un documento, debes editar de forma manual los artefactos relacionados, incluido el proxy de API y cualquier producto de API que exponga sus recursos, y volver a generar la documentación de referencia de la API para reflejar los cambios implementados en el documento.
- Si borras un documento, deberás borrar de forma manual los artefactos relacionados, incluido el proxy de API, y editar cualquier producto de API para borrar recursos relacionados, y volver a generar la documentación de referencia de la API para reflejar la eliminación del documento y sus recursos.
¿Qué sucede cuando creo un proxy de API a partir de un documento de OpenAPI?
Puedes crear tus proxies de API a partir de tus documentos de OpenAPI. Con solo unos clics, tendrás un proxy de API con las rutas, los parámetros, los flujos condicionales y los extremos de destino generados automáticamente. Luego puedes agregar características como la seguridad de OAuth, el límite de frecuencia y el almacenamiento en caché.
Puedes crear un proxy de API a partir de un documento de OpenAPI con el asistente de creación de proxy, como se describe en Usa especificaciones de OpenAPI para generar proxies. Para obtener una experiencia práctica, revisa el instructivo Crea un proxy de API a partir de una especificación de OpenAPI.
Cuando publicas la API, tomas una instantánea de un documento de OpenAPI para generar documentación de referencia de la API. Esa instantánea representa una revisión específica del documento de descripción.