Introduzione
Questa è una guida alla progettazione generale per le API di rete. Viene utilizzata all'interno di Google dal 2014 ed è la guida che Google segue per progettare le API Cloud e altre API di Google. Questa guida al design viene condivisa per informare gli sviluppatori esterni e semplificare la collaborazione tra tutti.
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 impostiamo l'utilizzo. Puoi utilizzare Cloud Endpoints e gRPC senza seguire la guida.
Questa guida si applica sia alle API REST che alle API RPC, con un'attenzione specifica alle API gRPC. Le API gRPC utilizzano Protocol Buffers per definire la propria API e API Service Configuration per configurare i propri servizi API, tra cui mappatura HTTP, logging e monitoraggio. Le funzionalità di mappatura HTTP vengono utilizzate dalle API Google e dalle API gRPC di Cloud Endpoints per la transcodifica di JSON/HTTP in Protocol Buffers/RPC.
Questa guida è un documento in continua evoluzione e verrà integrata nel tempo man mano che nuovi stili e pattern di design vengono adottati e approvati. In questo spirito, non sarà mai completa e ci sarà sempre ampio spazio per l'arte e la tecnica del design delle API.
Convenzioni utilizzate in questa guida
Le parole chiave per il livello di requisito "DEVE", "NON DEVE", "OBBLIGATORIO", "DEVE", "NON DEVE", "DEVE", "NON DEVE", "CONSIGLIATO", "PUÒ" e "FACOLTATIVO" utilizzate in questo documento devono essere interpretate come descritto nel RFC 2119.
In questo documento, queste parole chiave sono evidenziate in grassetto.
Sezioni
Progettazione orientata alle risorse
Per informazioni sull'implementazione del design orientato alle risorse per le API RPC e REST, consulta AIP-121.
Nomi delle risorse
Per informazioni sui nomi delle risorse, consulta AIP-122.
Metodi standard
Per informazioni generali sui metodi, consulta l'articolo AIP-130.
Per informazioni sui metodi standard, consulta i seguenti AIP:
- Per
Get, consulta AIP-131 - Per
List, consulta AIP-132 - Per
Create, consulta l'articolo AIP-133 - Per
Update, consulta l'articolo AIP-134 - Per
Delete, consulta l'AIP-135
Metodi personalizzati
Per informazioni sui metodi personalizzati, consulta l'articolo AIP-136.
Argomenti aggiuntivi
Per informazioni sui seguenti argomenti, consulta le AIP correlate.
- Per i campi standard, consulta AIP-148
- Per gli errori, consulta AIP-193
- Per i pattern di progettazione, consulta le linee guida AIP sui pattern di progettazione
- Per la documentazione dell'API in linea, consulta AIP-192
- Per l'utilizzo di proto3, consulta la sezione Sintassi dell'AIP-191
- Per il controllo delle versioni, consulta l'articolo AIP-185
- Per la compatibilità con le versioni precedenti, consulta l'AIP-180
- Per la struttura del file, consulta la sezione File Layout dell'AIP-191
- Per un glossario dei termini, consulta l'AIP-9
Per informazioni sui seguenti argomenti, consulta le pagine correlate in questa guida.