Guida alla progettazione delle API

Introduzione

Questa è una guida alla progettazione generale per le API in rete. È utilizzata all'interno di 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 semplificare la collaborazione.

Gli sviluppatori di Cloud Endpoints potrebbero trovare questa guida particolarmente utile durante la progettazione delle API gRPC e consigliamo vivamente 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 buffer di protocollo per definire la propria piattaforma API e la configurazione del servizio API per configurare i propri servizi API, tra cui mappatura, logging e monitoraggio HTTP. Le funzionalità di mappatura HTTP vengono utilizzate dalle API di Google e dalle API gRPC di Cloud Endpoints per la transcodifica di JSON/HTTP to Protocol Buffers/RPC.

Questa guida è un documento continuo e le aggiunte verranno aggiunte nel tempo man mano che nuovi stili e modelli di design verranno adottati e approvati. In questo spirito, non sarà mai completo e ci sarà sempre ampio spazio per l'arte e la tecnica della progettazione delle API.

Convenzioni utilizzate in questa guida

Le parole chiave a livello di requisito "DEV", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" utilizzate in questo documento devono essere interpretate come descritto nel documento RFC 2119.

In questo documento, queste parole chiave vengono evidenziate in grassetto.

Sezioni

Avanti

Progettazione orientata alle risorse