Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
En la fase de diseño, se definen los requisitos de la API. Como diseñador de APIs, planificas los servicios que quieres ofrecer a los consumidores y diseñas APIs para acceder a esos servicios. Crea uno de los siguientes documentos para registrar los requisitos de tu API:
- Un documento de OpenAPI
- Un esquema de GraphQL
En las siguientes secciones se ofrece más información sobre los documentos de OpenAPI y GraphQL, así como sobre el papel que desempeñan en el ciclo de vida de tu API. Para ver una comparación de las dos opciones de diseño de APIs, consulta la comparación entre REST y GraphQL en esta entrada de blog.
¿Qué es la especificación de OpenAPI?
"La iniciativa OpenAPI (OAI) se centra en crear, desarrollar y promover un formato de descripción de APIs independiente del proveedor basado en la especificación de Swagger". Para obtener más información sobre la iniciativa OpenAPI, consulta https://openapis.org.
Un documento de OpenAPI usa un formato estándar para describir una API RESTful. Los documentos OpenAPI, escritos en formato JSON o YAML, son legibles por máquinas, pero también fáciles de leer y entender para los humanos. La especificación de OpenAPI permite describir formalmente los elementos de una API, como su ruta base, sus rutas y verbos, sus encabezados, sus parámetros de consulta, sus tipos de contenido, sus modelos de respuesta y más. Además, se suele usar un documento de OpenAPI para generar documentación de la API.
A continuación, se muestra un fragmento de un documento de OpenAPI que describe el ejemplo sencillo de Hello World 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
...
Hay muchas fuentes de información excelentes sobre las especificaciones de OpenAPI. Un buen punto de partida es el sitio de la iniciativa OpenAPI, donde encontrarás resúmenes, blogs y enlaces a la especificación OpenAPI. Consulta la especificación para ver descripciones detalladas de los elementos de esquema y los tipos de datos.
Puedes descargar varios documentos OpenAPI de ejemplo en formato JSON y YAML 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 un cliente pueda consultarlos.
Estas son algunas de las ventajas de usar GraphQL:
- Un único endpoint proporciona acceso a todos los campos de una operación determinada
- El potente lenguaje de consulta, denominado lenguaje de definición de esquemas, te permite acceder exactamente a los datos que necesitas, lo que evita que se obtengan demasiados datos o que se obtengan pocos.
- El procesamiento de las consultas se realiza en paralelo
Para obtener más información sobre GraphQL, consulta graphql.org.
A continuación, se muestra un ejemplo de un esquema de GraphQL que define el punto de entrada de datos (tipo Query), las operaciones de escritura disponibles (tipo Mutation) 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 de GraphQL para devolver los datos exactos que necesites como carga útil de JSON.
¿Qué ocurre si modifico un documento?
Cada documento de OpenAPI o GraphQL sirve como fuente de información veraz a lo largo del ciclo de vida de la API. El mismo documento se usa en cada fase del ciclo de vida de la API, desde el desarrollo hasta la publicación y la monitorización.
Cuando editas o eliminas un documento, esto tiene consecuencias:
- Si editas un documento, debes editar manualmente los artefactos relacionados, como el proxy de API y los productos de API que expongan sus recursos, y volver a generar la documentación de referencia de la API para que refleje los cambios implementados en el documento.
- Si eliminas un documento, debes eliminar manualmente los artefactos relacionados, incluido el proxy de API, y editar los productos de API para eliminar los recursos relacionados. Además, debes volver a generar la documentación de referencia de la API para que se refleje la eliminación del documento y sus recursos.
¿Qué ocurre 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 endpoints de destino generados automáticamente. Después, puedes añadir funciones como seguridad de OAuth, limitación de frecuencia y almacenamiento en caché.
Puedes crear un proxy de API a partir de un documento de OpenAPI con el asistente para crear proxies, tal como se describe en el artículo Usar especificaciones de OpenAPI para generar proxies. Para disfrutar de una experiencia práctica, sigue el tutorial Crear un proxy de API a partir de una especificación de OpenAPI.
Cuando publicas tu API, haces una instantánea del documento de OpenAPI para generar la documentación de referencia de la API. Esa captura representa una revisión específica del documento de descripción.