Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Nella fase di progettazione, definisci i requisiti per la tua API. In qualità di progettista di API, pianifichi i servizi che vuoi esporre ai consumer e progetti le API per accedere a questi servizi. Crea uno dei seguenti documenti per acquisire i requisiti dell'API:
- Un documento OpenAPI
- Uno schema GraphQL
Le sezioni seguenti forniscono ulteriori informazioni sui documenti OpenAPI e GraphQL e sul ruolo che svolgono nel ciclo di vita dell'API. Per un confronto tra le due opzioni di progettazione delle API, consulta questo post del blog.
Che cos'è la specifica OpenAPI?
"L'OpenAPI Initiative (OAI) si concentra sulla creazione, l'evoluzione e la promozione di un formato di descrizione delle API indipendente dal fornitore basato sulla specifica Swagger". Per ulteriori informazioni sull'iniziativa OpenAPI, visita la pagina https://openapis.org.
Un documento OpenAPI utilizza un formato standard per descrivere un'API RESTful. Scritto in formato JSON o YAML, un documento OpenAPI è leggibile dal computer, ma anche facile da leggere e comprendere per gli esseri umani. La specifica OpenAPI consente la descrizione formale degli elementi di un'API, come il percorso di base, i percorsi e i verbi, le intestazioni, parametri di ricerca, i tipi di contenuti, i modelli di risposta e altro ancora. Inoltre, un documento OpenAPI viene comunemente utilizzato per generare la documentazione API.
Di seguito è riportato un frammento di un documento OpenAPI che descrive il semplice esempio Hello World di Apigee. Per maggiori informazioni, consulta la specifica OpenAPI su 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
...
Esistono molte fonti eccellenti di informazioni sulle specifiche OpenAPI. Un buon punto di partenza è il sito dell'OpenAPI Initiative, dove troverai panoramiche, blog e link alla specifica OpenAPI. Per descrizioni dettagliate degli elementi dello schema e dei tipi di dati, consulta le specifiche.
Esistono diversi documenti OpenAPI di esempio in formato JSON e YAML che puoi scaricare dal repository delle specifiche OpenAPI.
Che cos'è uno schema GraphQL?
Uno schema GraphQL descrive i dati disponibili nella tua API che un client può interrogare.
I vantaggi dell'utilizzo di GraphQL includono:
- Un unico endpoint fornisce l'accesso a tutti i campi per una determinata operazione
- Il potente linguaggio di query, chiamato Schema Definition Language, ti consente di accedere esattamente ai dati di cui hai bisogno, evitando il recupero eccessivo o insufficiente dei dati
- L'elaborazione delle query avviene in parallelo
Per ulteriori informazioni su GraphQL, visita il sito graphql.org.
Di seguito è riportato un esempio di schema GraphQL che definisce il punto di inserimento dei dati (tipo di query), le operazioni di scrittura disponibili (tipo di mutazione) e i tipi di dati.
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!
}
Puoi eseguire query sullo schema GraphQL per restituire i dati esatti di cui hai bisogno come payload JSON.
Che cosa succede se modifico un documento?
Ogni documento OpenAPI o GraphQL funge da fonte attendibile durante l'intero ciclo di vita dell'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita dell'API, dallo sviluppo alla pubblicazione al monitoraggio.
Quando modifichi o elimini un documento, le modifiche hanno un impatto a cascata:
- Se modifichi un documento, devi modificare manualmente gli artefatti correlati, inclusi il proxy API e tutti i prodotti API che espongono le relative risorse, e rigenerare la documentazione di riferimento dell'API per riflettere le modifiche implementate nel documento.
- Se elimini un documento, devi eliminare manualmente gli artefatti correlati, incluso il proxy API, e modificare i prodotti API per eliminare le risorse correlate, quindi rigenerare la documentazione di riferimento dell'API per riflettere la rimozione del documento e delle relative risorse.
Cosa succede quando creo un proxy API da un documento OpenAPI?
Puoi creare i tuoi proxy API dai documenti OpenAPI. In pochi clic avrai un proxy API con percorsi, parametri, flussi condizionali ed endpoint di destinazione generati automaticamente. Poi, puoi aggiungere funzionalità come la sicurezza OAuth, la limitazione di frequenza e la memorizzazione nella cache.
Puoi creare un proxy API da un documento OpenAPI utilizzando la procedura guidata di creazione del proxy, come descritto in Utilizzare le specifiche OpenAPI per generare proxy. Per un'esperienza pratica, segui il tutorial Creazione di un proxy API da una specifica OpenAPI.
Quando pubblichi l'API, acquisisci uno snapshot del documento OpenAPI per generare la documentazione di riferimento dell'API. Questo snapshot rappresenta una revisione specifica del documento di descrizione.