Google API 设计指南不完全摘要

原创
2017/03/15 13:44
阅读数 319

Google API 设计指南不完全摘要

全文:https://cloud.google.com/apis/design/

这个设计指南中有很多内容偏重于如何使用 gRPC 涉及 API,如果使用了 gRPC 建议详细阅读。但是,里面也有很多内容对 HTTP API 设计有指导意义,同样建议阅读。

介绍

这个指南可应用于 REST APIs 和 RPC APIs 的设计上,并侧重于 gRPC API 的设计。

This guide applies to both REST APIs and RPC APIs, with specific focus on gRPC APIs.

Resource Oriented Design

什么是 REST API (What is a REST API?)

A REST API is modeled as collections of individually-addressable resources (the nouns of the API). Resources are referenced with their resource names and manipulated via a small set of methods (also known as verbs or operations).

Standard methods for REST Google APIs (also known as REST methods) are List, Get, Create, Update, and Delete. Custom methods (also known as custom verbs or custom operations) are also available to API designers for functionality that doesn't easily map to one of the standard methods, such as database transactions.

设计流程 (Design flow)

The Design Guide suggests taking the following steps when designing resource- oriented APIs (more details are covered in specific sections below):

  • Determine what types of resources an API provides.
  • Determine the relationships between resources.
  • Decide the resource name schemes based on types and relationships.
  • Decide the resource schemas.
  • Attach minimum set of methods to resources.(最小化方法,同编程语言中的接口设计的思想一样,尽量少暴露方法)

方法 (Methods)

面向资源的 API 的关键特性是强调资源(数据模型)高于操作(实体有限才是符合面向对象设计。方法优先是面向过程的设计思想,这种思想不适合 API 设计)。一个典型的面向资源的接口会暴露大量的资源,但这些资源只带有少量的方法(操作)

The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality). A typical resource-oriented API exposes a large number of resources with a small number of methods.

例子

Gmail API

  • The Gmail API service implements the Gmail API and exposes most of Gmail functionality. It has the following resource model:
  • The Gmail API service: gmail.googleapis.com
    • A collection of users: users/*. Each user has the following resources.
    • A collection of messages: users/*/messages/*.
    • A collection of threads: users/*/threads/*.
    • A collection of labels: users/*/labels/*.
    • A collection of change history: users/*/history/*.
    • A resource representing the user profile: users/*/profile.
    • A resource representing user settings: users/*/settings.

Resource Names

In resource-oriented APIs, resources are named entities, and resource names are their identifiers. Each resource must have its own unique resource name.

The API service name is for clients to locate the API service endpoint; it may be a fake DNS name for internal-only services.

Errors

错误重试

Clients should retry on 500, 503, and 504 errors with exponential backoff. The minimum delay should be 1s unless it is documented otherwise. For 429 errors, the client may retry with minimum 30s delay. For all other errors, retry may not be applicable - first ensure your request is idempotent, and see the error message for guidance.

展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部