Panoramica sulla progettazione delle API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Nella fase di progettazione, devi definire i requisiti per l'API. In qualità di designer di API, pianifichi i servizi da esporre ai consumatori e progetti le API per l'accesso a questi servizi. Puoi creare 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 loro ruolo nel ciclo di vita dell'API. Per un confronto tra le due opzioni di progettazione delle API, consulta il confronto tra REST e GraphQL in questo post del blog.

Che cos'è la specifica OpenAPI?


"L'iniziativa OpenAPI (OAI) è incentrata sulla creazione, sull'evoluzione e sulla promozione di un formato di descrizione 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 dalle macchine e allo stesso tempo facile da leggere e comprendere per gli utenti. La specifica OpenAPI consente la descrizione formale degli elementi di un'API, come percorso di 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 relativa alle API.

Ecco un frammento di un documento OpenAPI che descrive il semplice esempio 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 fonti di informazioni eccellenti sulle specifiche OpenAPI. Un buon punto di partenza è il sito OpenAPI Initiative, dove troverai panoramiche, blog e link alla specifica OpenAPI. Fai riferimento alla specifica per descrizioni dettagliate degli elementi dello schema e dei tipi di dati.

È disponibile una serie di documenti OpenAPI di esempio JSON e YAML che puoi scaricare Repository delle specifiche OpenAPI.

Che cos'è uno schema GraphQL?

Uno schema GraphQL descrive i dati disponibili nella tua API per l'esecuzione di query da parte del client.

I vantaggi dell'utilizzo di GraphQL includono:

  • Un singolo endpoint fornisce l'accesso a tutti i campi di 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 il recupero insufficiente dei 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 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 una query sullo schema GraphQL per restituire i dati esatti di cui hai bisogno come payload JSON.

Query GraphQL e risultati

Che cosa succede se modifico un documento?

Ogni documento OpenAPI o GraphQL funge da fonte attendibile per tutto il ciclo di vita dell'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita delle API, dallo sviluppo alla pubblicazione e al monitoraggio.

Quando modifichi o elimini un documento, le modifiche hanno un impatto su tutta la linea:

  • Se modifichi un documento, devi modificare manualmente i relativi artefatti, tra cui il proxy API e tutti i prodotti API che espongono le sue risorse, quindi devi rigenerare 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 qualsiasi prodotto API per eliminare le risorse correlate e rigenerare la documentazione di riferimento API per riflettere la rimozione del documento e delle relative risorse.

Cosa succede quando creo un proxy API da un documento OpenAPI?

In Edge, puoi creare proxy API dai documenti OpenAPI. Con pochi clic, avrai a disposizione un proxy API con percorsi, parametri, flussi condizionali ed endpoint di destinazione generati automaticamente. Successivamente, 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, come descritto nelle sezioni seguenti:

Quando pubblichi l'API, crei uno snapshot del documento OpenAPI per generare la relativa documentazione di riferimento. Questo snapshot rappresenta una revisione specifica del documento descrittivo nell'archivio delle specifiche.