Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Na fase de design, você define os requisitos da API. Como designer de API, você planeja os serviços que quer expor aos consumidores e cria APIs para acessá-los. Crie um dos seguintes documentos para registrar os requisitos da API:
- Um documento da OpenAPI
- Um esquema GraphQL;
As seções a seguir fornecem mais informações sobre os documentos da WebGL e do GraphQL e os papéis deles no ciclo de vida da sua API. Para ver uma comparação das duas opções de design de API, consulte REST e GraphQL em comparação com esta postagem do blog.
O que é a especificação do OpenAPI?
"A Open API Initiative (OAI) tem como foco criar, desenvolver e promover um formato de descrição de API desvinculado de fornecedor com base na especificação Swagger." Para mais informações sobre a OpenAPI Initiative, consulte https://openapis.org.
Um documento OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita em formato JSON ou YAML, um documento OpenAPI é legível por máquina, mas também é fácil de ler e entender por pessoas. A especificação da OpenAPI permite uma descrição formal de elementos de uma API, como o caminho base, caminhos e verbos, cabeçalhos, parâmetros de consulta, tipos de conteúdo, modelos de resposta e muito mais. Além disso, um documento OpenAPI é comumente usado para gerar a documentação da API.
Veja um fragmento de um documento OpenAPI que descreve a amostra simples "Hello World" da Apigee. Para mais informações, consulte a especificação OpenAPI no 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
...
Há diversas fontes de informações excelentes sobre as especificações OpenAPI. Um bom lugar para começar é o site da OpenAPI Initiative, onde você encontra visões gerais, blogs e links para a especificação da OpenAPI. Consulte os documentos para descrições detalhadas dos elementos de esquema e dos tipos de dados.
Há várias documentos de OpenAPI de exemplo JSON e YAML que podem ser salvos no repositório de especificação OpenAPI.
O que é um esquema do GraphQL?
Um esquema do GraphQL descreve os dados disponíveis na sua API que um cliente pode consultar.
Os benefícios de usar o GraphQL incluem o seguinte:
- Um único endpoint oferece acesso a todos os campos de uma determinada operação.
- A linguagem de consulta avançada, chamada de Definição de esquema, permite que você acesse exatamente os dados de que precisa, evitando a busca excessiva ou reduzida de dados
- O processamento de consultas acontece em paralelo
Para mais informações sobre o GraphQL, consulte graphql.org.
Veja a seguir um exemplo de esquema GraphQL que define o ponto de entrada de dados (tipo de consulta), as operações de gravação disponíveis (tipo de mutação) e os tipos de dados.
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!
}
É possível consultar o esquema do GraphQL para retornar os dados exatos necessários como um payload JSON.
O que acontece se eu modificar um documento?
Cada documento do WebGL ou GraphQL serve como a fonte da verdade durante todo o ciclo de vida da API. O mesmo documento é usado em cada fase do ciclo de vida da API, desde o desenvolvimento até a publicação e o monitoramento.
Quando você edita ou exclui um documento, ele afeta o futuro:
- Se você editar um documento, precisará editar manualmente os artefatos relacionados, incluindo o proxy de API e todos os produtos de API que expõem os recursos, e gerar novamente a documentação de referência da API para refletir as alterações implementadas no documento.
- Se você excluir um documento, será necessário excluir manualmente os artefatos relacionados, incluindo o proxy de API e editar todos os produtos de API para excluir os recursos relacionados, e gerar novamente a documentação de referência da API para refletir a remoção do documento e dos recursos dele.
O que acontece quando eu crio um proxy de API com base em um documento OpenAPI?
É possível criar proxies de API com base nos documentos OpenAPI. Com apenas alguns cliques, você terá um proxy de API com os caminhos, parâmetros, fluxos condicionais e endpoints de destino gerados automaticamente. Em seguida, será possível adicionar recursos como segurança OAuth, limitação de taxa e armazenamento em cache.
É possível criar um proxy de API com base em um documento OpenAPI usando o assistente de criação de proxy, conforme descrito em Como usar especificações OpenAPI para gerar proxies. Para uma experiência prática, siga as etapas do tutorial Criar um proxy de API com base em uma especificação OpenAPI.
Quando você publica a API, captura um snapshot do documento OpenAPI para gerar a documentação de referência da API. O snapshot representa uma revisão específica do documento de descrição.