Introduzione
Questa è una guida generale alla progettazione per le API di rete. È stata utilizzata all'interno Google dal 2014 ed è la guida che Google segue quando progetta API Cloud e altre API di Google. Questa guida alla progettazione è condivisa qui per informare gli sviluppatori esterni e per noi tutti collaborare.
Gli sviluppatori di Cloud Endpoints possono trovarla utile per la progettazione delle API gRPC, e consigliamo vivamente tali sviluppatori utilizzano questi principi di progettazione. Tuttavia, non ne imponiamo l'utilizzo. Puoi utilizzare Cloud Endpoints e gRPC senza seguire la guida.
Questa guida riguarda sia le API REST che le API RPC, con particolare attenzione a gRPC su quelle di livello inferiore. Le API gRPC utilizzano Protocol Buffer per definire la superficie API e API Service Configuration per configurare i relativi servizi API, tra cui: Mappatura, logging e monitoraggio HTTP. 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 dinamico e le relative aggiunte verranno apportate nel tempo man mano che nuovi stili e modelli di design vengono adottati e approvati. In questo spirito personale, non sarà mai completa e ci sarà sempre per l'arte e l'arte della progettazione delle API.
Convenzioni utilizzate in questa guida
Le parole chiave a livello di requisito "MUST", "MUST NOT", "REQUIRED", "SHALL", "NON DEVE", "NON DEVE", "NON DEVE", "CONSIGLIATO", "MAGGIO" e "FACOLTATIVO" utilizzati in questo documento devono essere interpretati come descritto nella 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
- Design Patterns
- Documentazione
- Utilizzo di Proto3
- Controllo delle versioni
- Compatibilità
- Struttura della directory
- Struttura dei file
- Glossario