Introduzione
Si tratta di una guida generale alla progettazione per le API di rete. Viene utilizzata internamente da Google dal 2014 ed è la guida che Google segue durante la progettazione delle API Cloud e di altre API di Google. Questa guida alla progettazione viene condivisa qui per informare gli sviluppatori esterni e per facilitare la collaborazione.
Gli sviluppatori di Cloud Endpoints potrebbero trovare questa guida particolarmente utile per la progettazione di API gRPC e consigliamo vivamente a questi sviluppatori di utilizzare questi principi di progettazione. Tuttavia, non ne imponiamo l'utilizzo. Puoi utilizzare Cloud Endpoints e gRPC senza seguire la guida.
Questa guida si applica sia alle API REST sia alle API RPC, con particolare attenzione alle API gRPC. Le API gRPC utilizzano Protocol Buffer per definire la propria superficie API e la configurazione del servizio API per configurare i propri servizi API, inclusi mapping HTTP, logging e monitoraggio. Le funzionalità di mappatura HTTP vengono utilizzate dalle API Google e dalle API gRPC di Cloud Endpoints per la transcodifica da JSON/HTTP a Protocol Buffer/RPC.
Questa guida è un documento in continua evoluzione e nel tempo verranno aggiunti nuovi stili e pattern di progettazione man mano che verranno adottati e approvati. In questo spirito, non sarà mai completo e ci sarà sempre ampio spazio per l'arte e l'artigianato della progettazione di API.
Convenzioni utilizzate in questa guida
Le parole chiave relative al livello di requisito "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" utilizzate in questo documento devono essere interpretate come descritto in RFC 2119.
In questo documento, queste parole chiave sono evidenziate utilizzando il carattere grassetto.
Sezioni
Progettazione orientata alle risorse
Per informazioni sull'implementazione della progettazione orientata alle risorse per le API RPC e REST, consulta AIP-121.
Nomi delle risorse
Per informazioni sui nomi delle risorse, vedi AIP-122.
Metodi standard
Per informazioni generali sui metodi, consulta AIP-130.
Per informazioni sui metodi standard, consulta le seguenti AIP:
- Per
Get, vedi AIP-131 - Per
List, vedi AIP-132 - Per
Create, vedi AIP-133 - Per
Update, vedi AIP-134 - Per
Delete, vedi AIP-135
Metodi personalizzati
Per informazioni sui metodi personalizzati, vedi AIP-136.
Argomenti aggiuntivi
Per informazioni sui seguenti argomenti, consulta le AIP correlate.
- Per i campi standard, vedi AIP-148
- Per gli errori, consulta AIP-193
- Per i pattern di progettazione, consulta le indicazioni di AIP sui pattern di progettazione.
- Per la documentazione dell'API in linea, consulta AIP-192.
- Per Utilizzo di proto3, consulta la sezione Sintassi di AIP-191
- Per il controllo delle versioni, vedi AIP-185
- Per la compatibilità con le versioni precedenti, consulta AIP-180
- Per la struttura dei file, consulta la sezione Layout file di AIP-191.
- Per un glossario dei termini, consulta AIP-9.
- Per le convenzioni di denominazione, consulta AIP-190.
Per informazioni sui seguenti argomenti, consulta le pagine correlate in questa guida.