Enjoy software architecture and programming

06 Dec 2022

PayPal API 设计指南(1)

1626 words - 9 mins

一、介绍

PayPal 平台是一组可重用的服务,封装了定义明确的业务功能。 鼓励开发人员通过应用程序编程接口 (API) 访问这些功能,以实现一致的设计模式和原则。 这有助于获得出色的开发人员体验,并能通过将多个互补功能组合为构建块,来快速构建复杂的业务流程。

PayPal 为尽可能遵循 RESTful 架构风格。 制定了一套适用于 RESTful API 设计的规则、标准和约定。 这些已被用于帮助设计和维护数百个 API,并且经过数年的发展,满足了各种用例的需求。

文档语义、格式和命名

本文档中的关键字“必须”("MUST")、“不得”("MUST NOT")、“必需”("REQUIRED")、“应”("SHALL")、“不应”("SHALL NOT")、“应该”("SHOULD")、“不应”("SHOULD NOT")、“推荐”("RECOMMENDED")、“可以”("MAY")和“可选”("OPTIONAL"),应按照 RFC 2119 中的说明进行解释。

“REST”和“RESTful”这两个词必须按照此处所示的方式书写,将首字母缩写词全部大写。 “JSON”、“XML”和其他缩写词也是如此。

机器可读文本(如 URL、HTTP 谓词和源代码)使用固定宽度的字体表示。

包含变量块的 URI 是根据 URI Template RFC 6570 指定的。例如,包含名为 account_id 的变量的 URL 将展示为 https://foo.com/accounts/{account_id}/。

HTTP 标头(HTTP headers)以驼峰大小写 + 连字符语法编写,例如 Foo-Request-Id。

二、使用的术语

资源(Resource)

REST 中信息的关键抽象是资源。 根据 Fielding 的论文第 5.2 节,任何可以命名的信息都可以是资源:文档或图像、临时服务(例如“洛杉矶今天的天气”)、其他资源的集合、非虚拟对象(例如某个人)等等。 资源是到一组实体的概念映射,而不是与任何特定时间点的映射对应的实体。 更准确地说,资源 R 是一个随时间变化的成员函数 MR(t),对于时间 t 映射到一组等效的实体或值。 该集合中的值可以是资源表示形式和/或资源标识符。

资源也可以映射到空集,允许在某个概念的任何实现存在之前对该概念进行引用。

资源标识符(Resource Identifier)

REST 使用资源标识符来标识组件间交互中涉及的特定资源实例。 分配资源标识符以便能够引用资源的命名机构(例如,提供 API 的组织),负责随着时间的推移维护映射的语义有效性(确保成员函数不改变)。 —— Fielding 的论文第 5.2 节

表征(Representation)

REST 组件通过使用表征(Representation)来捕获该资源的当前或预期状态,并通过在组件之间传输该表征来对资源执行操作。 表征是字节序列,加上描述这些字节的表征元数据 —— Fielding 的论文第 5.2 节

领域(Domain)

根据维基百科,领域模型是一个抽象系统,用于描述知识、影响或活动的选定方面。 这些概念包括业务中涉及的数据,以及业务使用的与该数据相关的规则。 例如,PayPal 领域模型包括支付、风险、合规性、身份、客户支持等领域。

功能(Capability)

功能表示组织业务逻辑的面向业务和面向客户的视图。功能可用于将 API 组合组织为稳定的、业务驱动的系统视图,供客户和体验使用。功能的示例包括:合规性、信用、身份、零售和风险等。

功能驱动界面,而领域是更粗粒度,更接近代码和组织结构。从服务的角度来看,功能和领域被视为正交关注点。

命名空间(Namespace)

功能驱动 API 组合中的服务建模和命名空间问题。命名空间是业务能力模型的一部分。命名空间的示例有:合规性、设备、传输、信用、限制等。

命名空间应反映在逻辑上对一组业务功能进行分组的领域。领域定义应反映客户对平台功能组织方式的看法。 请注意,这些可能不一定反映公司的层次结构、组织或(现有)代码结构。 在某些情况下,领域定义是理想的,因为它们反映了目标、面向客户的平台组织模型。随着时间的推移,底层服务实现和组织结构可能需要迁移以反映这些边界。

服务(Service)

服务提供通用的 API,用于访问和操作资源的值集,而不考虑成员函数是如何定义,或处理请求的软件类型如何。服务是可以执行任意数量功能的通用软件。 因此,考虑存在不同类型的服务是有好处的。

从逻辑上讲,我们可以将服务和它们公开的 API 分为两类:

  1. 功能 API(Capability APIs) 是由实现通用、可重用业务功能的服务公开的公共 API。
  2. 特定于体验的 API(Experience-specific APIs) 构建在功能 API 之上,并公开可能特定于渠道的功能,或者针对通用功能的特定于上下文的专业化进行优化。上下文信息可能与时间、位置、设备、频道、身份、用户、角色、权限级别等相关。

基于功能的服务和 API

功能 API 是可重用业务功能的公共接口。公共意味着这些 API 仅限于供前端体验、外部使用者或来自不同领域的内部使用者使用的接口。

基于体验的服务和 API

特定于体验的服务在核心功能上提供最少的额外业务逻辑,主要提供转换和轻量级编排,以根据特定体验、渠道或设备的需求定制交互。它们的输入/输出功能仅限于服务调用。

客户端、API 客户端、API 消费者

调用 API 请求并使用 API 响应的实体。

(未完待续)

原文链接:https://github.com/pzy-io/paypal-api-standards/blob/master/api-style-guide.md