Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Nella fase di progettazione, devi definire i requisiti dell'API. In qualità di designer di API, pianifichi i servizi che vuoi esporre ai consumatori e progetti le API per accedere a questi servizi. Crei uno dei seguenti documenti per acquisire i requisiti dell'API:
- Un documento OpenAPI
- Uno schema GraphQL
Le seguenti sezioni forniscono ulteriori informazioni sui documenti OpenAPI e GraphQL e sul loro ruolo nel ciclo di vita dell'API. Per un confronto tra le due opzioni di progettazione delle API, vedi REST e GraphQL a confronto in questo post del blog.
Che cos'è la specifica OpenAPI?
"OpenAPI Initiative (OAI) si concentra sulla creazione, lo sviluppo e la promozione di un formato di descrizione dell'API indipendente dal fornitore e basato sulla specifica Swagger." Per ulteriori informazioni sull'iniziativa OpenAPI, visita il sito 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 dalla macchina, ma anche di facile lettura e comprensione per le persone. La specifica OpenAPI consente la descrizione formale degli elementi di un'API, ad esempio percorso base, percorsi e verbi, intestazioni, parametri di query, tipi di contenuti, modelli di risposta e altro ancora. Inoltre, un documento OpenAPI viene comunemente utilizzato per generare la documentazione dell'API.
Ecco un frammento di un documento OpenAPI che descrive il semplice esempio di Hello World di Apigee. Per ulteriori informazioni, visualizza 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 ottime fonti di informazioni sulle specifiche OpenAPI. Un buon punto di partenza è il sito OpenAPI Initiative, dove troverai panoramiche, blog e link alle specifiche OpenAPI. Per le descrizioni dettagliate degli elementi dello schema e dei tipi di dati, consulta la specifica.
Sono disponibili diversi documenti OpenAPI di esempio JSON e YAML che puoi scaricare dal repository delle specifiche OpenAPI.
Che cos'è uno schema GraphQL?
Uno schema GraphQL descrive i dati disponibili nell'API su cui un client può eseguire query.
GraphQL offre diversi vantaggi, tra cui:
- Un singolo endpoint fornisce l'accesso a tutti i campi per una determinata operazione
- L'efficace linguaggio di query, chiamato Schema Definition Language, ti consente di accedere esattamente ai dati di cui hai bisogno, evitando di sovraccaricare o recuperare i dati
- L'elaborazione delle query avviene in parallelo
Per ulteriori informazioni su GraphQL, consulta graphql.org.
Di seguito è riportato un esempio di schema GraphQL che definisce il punto di ingresso 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 per 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 fino al monitoraggio.
La modifica o l'eliminazione di un documento ha effetto su tutta la linea:
- Se modifichi un documento, devi modificare manualmente gli artefatti correlati, incluso il proxy API e gli eventuali prodotti API che espongono le relative risorse, e generare nuovamente la documentazione di riferimento API per riflettere le modifiche implementate nel documento.
- Se elimini un documento, devi eliminare manualmente gli artefatti correlati, incluso il proxy API, modificare tutti i prodotti API per eliminare le risorse correlate e rigenerare la documentazione di riferimento API in modo che rifletta la rimozione del documento e delle relative risorse.
Che cosa succede quando creo un proxy API da un documento OpenAPI?
In Edge, puoi creare proxy API dai tuoi documenti OpenAPI. In pochi clic sarà disponibile un proxy API con percorsi, parametri, flussi condizionali ed endpoint di destinazione generati automaticamente. Successivamente, puoi aggiungere funzionalità quali la sicurezza OAuth, la limitazione della frequenza e la memorizzazione nella cache.
Puoi creare un proxy API da un documento OpenAPI, come descritto nelle sezioni seguenti:
- Dall'elenco delle specifiche, come descritto in Creazione di un proxy API da una specifica nell'elenco delle specifiche. Nota: l'elenco delle specifiche non è disponibile nella versione classica di Edge.
- Dal gestore dei proxy API richiamando la procedura guidata di creazione del proxy e scegliendo di creare il proxy API da un documento OpenAPI, come descritto in Utilizzo delle specifiche OpenAPI per generare proxy.
Quando pubblichi la tua API, crei un'istantanea del documento OpenAPI per generare la documentazione di riferimento dell'API. Lo snapshot rappresenta una revisione specifica del documento descrittivo nell'archivio delle specifiche.