Google a publié un Guide de Conception d'API pour la création d'APIs HTTP ou RPC. Ces principes de conception sont recommandés en particulier aux développeurs qui créent des APIs gRPC se connectant à Google Cloud Endpoints.
Google a utilisé ce guide de conception en interne depuis 2014 pour la création d'APIs cloud ou d'autres services. Le guide traite de la conception des APIs HTTP ou RPC. Tout en reconnaissant les mérites des APIs HTTP (également appelées API REST), mentionnant qu'il y a des moments où ils font sens d'être utilisés, Google préfère RPC et en particulier sa variante gRPC. Alors que la plupart des APIs Internet sont HTTP, ceux utilisés en interne par les fournisseurs cloud et de services sont en général RPC, surpassant largement les APIs HTTP, selon Google.
Google recommande une approche REST pour concevoir des APIs RPC : il s'agit fondamentalement d'une ou plusieurs ressources qui sont exploitées par des méthodes. Les ressources, également appelées entités du domaine, sont identifiées par des URIs ou des noms uniques (ID) suivant un format de chemin réseau. Les ressources du même type peuvent être regroupées en collections.
Les méthodes standard à utiliser sont Create, Delete, Get, List et Update. Il est possible de créer des méthodes personnalisées pour les opérations qui ne peuvent pas être associées à l'une des méthodes standard, comme les transactions de base de données. Il est recommandé d'utiliser autant de ressources que nécessaire avec un petit nombre de méthodes.
Les étapes suivantes sont suggérées lors de la création de ressources :
- Déterminer les types de ressources fournis par l'API.
- Déterminer les relations entre les ressources.
- Décider les schémas de nom de ressource en fonction des types et des relations.
- Décider des schémas de ressources.
- Associer un minimum de méthodes aux ressources.
Pour le contrôle de version, Google utilise le versionage sémantique représenté par trois nombres comme dans MAJOR.MINOR.PATCH. Une version préliminaire est indiquée par un suffixe, tel que 1.0.0-alpha.
Le guide contient plus de détails et d'exemples sur les ressources, les méthodes standard et personnalisées, les champs standard, les erreurs, la création d'API avec proto3 et plus encore.