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 分为两类：
- 功能 API（Capability APIs） 是由实现通用、可重用业务功能的服务公开的公共 API。
- 特定于体验的 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