Você está visualizando a documentação do Apigee Edge.
Acesse a
documentação da
Apigee X. info
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?
No Edge, é possível criar proxies de API com base nos documentos da 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 da OpenAPI, conforme descrito nas seções a seguir:
- Na lista de especificações, conforme descrito em Como criar um proxy de API a partir de uma especificação na lista de especificações. Observação: a lista de especificações não está disponível no Edge clássico.
- No gerenciador de proxies da API, invoque o assistente de proxy de build e escolha criar seu proxy de API a partir de um documento da OpenAPI, conforme descrito em Como usar especificações da OpenAPI para gerar proxies.
Quando você publica a API, captura um snapshot do documento OpenAPI para gerar a documentação de referência da API. Esse snapshot representa uma revisão específica do documento de descrição no armazenamento de especificações.