文档章节

Google API 设计指南不完全摘要

编走编想
 编走编想
发布于 2017/03/15 13:44
字数 647
阅读 96
收藏 0

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.

© 著作权归作者所有

共有 人打赏支持
编走编想
粉丝 150
博文 128
码字总数 111395
作品 0
海淀
程序员
私信 提问
组件接口(API)设计指南-目录

组件接口(API)设计指南-目录 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-委托(delegate)和数据源协议(data-s...

cuibo1123
2014/10/08
0
0
通用编码器&解码器框架--seq2seq

seq2seq 是 Google 开源的一款用于 TensorFlow 的通用编码器&解码器框架(encoder-decoder framework),可用于机器翻译、文本摘要、会话建模、图像描述等。 设计目标/特性 通用性:Google ...

匿名
2017/03/16
909
0
Google 开源 seq2seq,通用编码器&解码器框架

谷歌又开源了,这次是开源了一款用于 TensorFlow 的通用编码器&解码器框架(encoder-decoder framework),可用于机器翻译、文本摘要、会话建模、图像描述等。 设计目标/特性 通用性:Googl...

王练
2017/03/16
1K
8
关于Android资源站

谷歌开发者中国站 Google Developers 中国网站是特别为中国开发者而建立的,它汇集了 Google 为全球开发者所提供的开发技术资源,包括 API 文档、开发案例、技术培训的视频。 Android官方开发...

请天点
2016/12/14
511
0
正式发布 Android 架构组件 1.0 稳定版

点此查看真人版中文介绍视频:v.qq.com/x/page/r050… 几十亿的设备都在用 Android 系统,从高端手机到飞机上的影音娱乐系统,应有尽有,不一而足。而 Android OS 则为这几十亿的设备保驾护航...

Android_开发者
2017/11/08
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Hibernate SQLite方言

以下代码有参考过github上国外某位大佬的,在发文的最新稳定版Hibernate上是可用的,有时间再仔细分析一下 import org.hibernate.dialect.Dialect;import org.hibernate.dialect.function.S...

CHONGCHEN
今天
3
0
CentOS 7 MariaDB搭建主从服务器

本文编写环境为CentOS7。确保关闭SELinux,关闭防火墙或者防打开指定端口。具体信息如下 #master[root@promote ~]# cat /etc/redhat-release CentOS Linux release 7.6.1810 (Core) [r...

白豆腐徐长卿
今天
10
0
介绍python中运算符优先级

下面这个表给出Python的运算符优先级,从最低的优先级(最松散地结合)到最高的优先级(最紧密地结合)。这意味着在一个表达式中,Python会首先计算表中较下面的运算符,然后在计算列在表上部...

问题终结者
今天
3
0
Spring Boot 2.x基础教程:快速入门

简介 在您第1次接触和学习Spring框架的时候,是否因为其繁杂的配置而退却了?在你第n次使用Spring框架的时候,是否觉得一堆反复黏贴的配置有一些厌烦?那么您就不妨来试试使用Spring Boot来让...

程序猿DD
昨天
10
0
SpringSecurity认证流程源码级详解

SpringSecurity认证流程源码级详解 认证流程说明 认证结果如何在多个请求之间共享 获取认证用户信息

chendom
昨天
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部