Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do Apigee Edge. 
Na fase de design, define os requisitos da sua API. Enquanto criador de APIs, planeia os serviços que quer expor aos consumidores e cria APIs para aceder a esses serviços. Crie um dos seguintes documentos para captar os requisitos da API:
- Um documento OpenAPI
- Um esquema GraphQL
As secções seguintes fornecem mais informações sobre os documentos OpenAPI e GraphQL, e o papel que desempenham no ciclo de vida da sua API. Para uma comparação das duas opções de design de API, consulte a comparação entre REST e GraphQL nesta publicação no blogue.
O que é a especificação OpenAPI?
"A OpenAPI Initiative (OAI) está focada na criação, evolução e promoção de um formato de descrição de API neutro para fornecedores 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. Escrito no formato JSON ou YAML, um documento OpenAPI é legível por computador, mas também é fácil de ler e compreender para os humanos. A especificação OpenAPI permite a descrição formal de elementos de uma API, como o respetivo 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 é usado frequentemente para gerar documentação da API.
Segue-se um fragmento de um documento OpenAPI que descreve o exemplo simples "Olá, mundo" do 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 ... Existem muitas excelentes fontes de informações sobre as especificações da OpenAPI. Um bom ponto de partida é o site da OpenAPI Initiative, onde encontra vistas gerais, blogs e links para a especificação OpenAPI. Consulte a especificação para ver descrições detalhadas dos elementos do esquema e dos tipos de dados.
Existem vários exemplos de documentos OpenAPI em JSON e YAML que pode transferir do repositório da especificação OpenAPI.
O que é um esquema GraphQL?
Um esquema GraphQL descreve os dados disponíveis na sua API para uma consulta de um cliente.
Seguem-se algumas vantagens da utilização do GraphQL:
- Um único ponto final fornece acesso a todos os campos para uma determinada operação
- A linguagem de consulta avançada, denominada linguagem de definição de esquemas, permite-lhe aceder exatamente aos dados de que precisa, evitando a obtenção excessiva ou insuficiente de dados
- O processamento de consultas ocorre em paralelo
Para mais informações sobre o GraphQL, consulte graphql.org.
Segue-se um exemplo de um esquema GraphQL que define o ponto de entrada de dados (tipo de consulta), as operações de escrita 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! } Pode consultar o esquema GraphQL para devolver os dados exatos de que precisa como um payload JSON.
O que acontece se modificar um documento?
Cada documento OpenAPI ou GraphQL serve como fonte de informações fidedignas ao longo do ciclo de vida da API. O mesmo documento é usado em cada fase do ciclo de vida da API, desde o desenvolvimento à publicação e à monitorização.
Quando edita ou elimina um documento, isso tem impacto no futuro:
- Se editar um documento, tem de editar manualmente os artefactos relacionados, incluindo o proxy de API e quaisquer produtos de API que exponham os respetivos recursos, e regenerar a documentação de referência da API para refletir as alterações implementadas no documento.
- Se eliminar um documento, tem de eliminar manualmente os artefactos relacionados, incluindo o proxy de API, e editar todos os produtos de API para eliminar os recursos relacionados, bem como regenerar a documentação de referência da API para refletir a remoção do documento e dos respetivos recursos.
O que acontece quando crio um proxy de API a partir de um documento OpenAPI?
Pode criar os seus proxies de API a partir dos seus documentos OpenAPI. Com apenas alguns cliques, tem um proxy de API com os caminhos, os parâmetros, os fluxos condicionais e os pontos finais de destino gerados automaticamente. Em seguida, pode adicionar funcionalidades como segurança OAuth, limitação de taxa e colocação em cache.
Pode criar um proxy de API a partir de um documento OpenAPI através do assistente de criação de proxies, conforme descrito no artigo Usar especificações OpenAPI para gerar proxies. Para uma experiência prática, siga o tutorial Criar um proxy de API a partir de uma especificação OpenAPI.
Quando publica a sua API, tira uma captura de ecrã do documento OpenAPI para gerar documentação de referência da API. Esse instantâneo representa uma revisão específica do documento de descrição.