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 aux API RPC, avec un accent particulier sur les API gRPC. Ces dernières utilisent les tampons de protocole pour définir la surface de leurs API et le service de configuration d'API pour configurer leurs services d'API, y compris la mise en correspondance HTTP, la journalisation et la surveillance. Les fonctionnalités de mise en correspondance HTTP sont utilisées par les API Google et les API gRPC Cloud Endpoints pour JSON/HTTP en vue du 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.
Sections
- Conception orientée ressources
- Noms de ressources
- Méthodes standards
- Méthodes personnalisées
- Champs standards
- Erreurs
- Conventions d'attribution de noms
- Modèles de conception
- Documentation
- Utiliser proto3
- Gestion des versions
- Compatibilité
- Structure des répertoires
- Structure des fichiers
- Glossaire