Guide de conception d'API

Date de publication : 2017-02-21. Journal des modifications

Présentation

Ceci est un guide de conception général pour les API en réseau. Il est utilisé par Google depuis 2014 et constitue le guide que Google suit lors de la conception d'API Cloud et d'autres API Google. Ce guide de conception est partagé ici pour informer les développeurs externes et pour faciliter notre collaboration.

Les développeurs Cloud Endpoints peuvent trouver ce guide particulièrement utile lors de la conception d'API gRPC, et nous recommandons vivement à ces développeurs d'utiliser ces principes de conception. Cependant, nous n'imposons pas son utilisation. Vous pouvez utiliser Cloud Endpoints et gRPC sans suivre le guide.

Ce guide s'applique aux API REST et RPC, et en particulier aux API gRPC. Les API gRPC utilisent Protocol Buffers pour définir leur surface d'API et API Service Configuration pour configurer leurs services d'API, y compris le mappage HTTP, la journalisation et la surveillance. Les fonctionnalités de mappage HTTP sont utilisées par les API Google et les API gRPC de Cloud Endpoints pour JSON/HTTP vers le transcodage RPC/Protocol Buffers.

Ce guide est un document évolutif auquel des ajouts seront apportés au fil du temps, à mesure que de nouveaux styles et modèles de conception seront adoptés et approuvés. Dans cet esprit, il ne sera jamais complet et il y aura toujours beaucoup de place pour l'innovation et la créativité dans la conception d'API.

Conventions utilisées dans ce guide

Les mots clés de niveau d’exigence "EST TENU DE", "OBLIGATOIRE", "DOIT", "NE DOIT PAS", "DEVRAIT", "NE DEVRAIT PAS", "RECOMMANDÉ", "PEUT" et "FACULTATIF" utilisés dans ce document doivent être interprétés tel que décrit dans le protocole RFC 2119.

Dans ce document, les mots clés sont mis en évidence grâce au format gras.

Rubriques