Introduzione
Questa è una guida generale alla progettazione di API in 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 richiediamo 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 da Google API e API gRPC di Cloud Endpoints per JSON/HTTP a buffer di protocollo/RPC transcodifica.
Questa guida è un documento in continua evoluzione e verrà integrata nel tempo man mano che vengono adottati e approvati nuovi stili e pattern di design. 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 vengono evidenziate in grassetto.
Sezioni
- Design orientato alle risorse
- Nomi delle risorse
- Metodi standard
- Metodi personalizzati
- Campi standard
- Errori
- Convenzioni di denominazione
- Modelli di design
- Documentazione
- Utilizzo di Proto3
- Controllo delle versioni
- Compatibilità
- Struttura della directory
- Struttura del file
- Glossario