vlambda博客
学习文章列表

关键企业资源或系统记录需要打开或公开为一组API，供所有下游系统构建逻辑/体验这些服务。对于绿地项目，系统 API 通常表示作为功能的一部分而开发的记录系统或数据存储系统。对于企业来说，系统API代表了所有的企业系统，比如核心企业资源规划（< strong>ERP）系统、运营数据存储、大型机应用程序或许多 商业现成（ COTS) 产品，例如 c客户关系管理 (CRM)等运行核心的 企业的流程。 ofsystem API 如下：

纯粹主义者会说系统 API 公开了 systems 的核心功能，应用程序应该将系统 API 的功能混搭起来为最终客户提供必要的功能。这可能适用于较小的应用程序或应用程序的初始迭代。随着应用程序变得越来越大，或者您开始​​跨多个渠道或设备公开功能，您开始查看功能开始被复制的场景，这意味着缺乏重用导致更难维护系统。流程 API 的一些显着特征如下：

最后的 API 分类是通道 API。正如 name 所暗示的，这些 API 是特定于渠道的，并映射到作为应用程序的一部分构建的客户旅程.这些也称为体验 API 或旅程 API。例如，如果您使用 Angular 或 React 构建应用程序，则属于 单页应用程序 (SPA) 需要映射到可由通道 API 提供的底层服务。通道 API 的一些显着特征如下：

资源名称通常指的是从 business 域中提取的名词。一旦确定了名词，API 合约就可以建模为针对这些名词的 HTTP 动词：

这取决于您如何对待资源——作为单例还是作为集合。因此，理想情况下，您最终会得到一个资源的两个基本 URL，一个用于 collection，另一个用于实体。例如：

使用 standard HTTP 状态码来指示问题/错误：

示例错误消息如以下代码段所示：

{ 
   "type": "error", 
   "status":400, 
   "code": "bad_request", 
   "context_info": { 
         "errors": [ 
         { 
               "reason": "missing_argument", 
               "message": "order_id is required", 
               "name": "order_id", 
               "location": "query_param" 
         } 
         ] 
   }, 
   "help_url": "http://developers.some.com/api/docs/#error_code", 
   "message": "Bad Request" 
   "request_id": "8233232980923412494933" 
} Copy

HTTP 代码使用示例如下：

服务版本控制有多个模型：

请记住，资源是一种语义模型；资源的表示形式和状态可能会随着时间而改变，但标识符必须始终如一地处理相同的资源。因此，只有在概念发生潜在变化时才应使用新的 URI。 API 外观层可以从底层服务和模式版本中抽象出北向 API。 API 管理平台支持创建 API 外观层。

使用带有分页 information 的 URL 来处理结果偏移和限制。例如，/orders?limit=25&offset=50。

API 应支持提供消费者使用 查询参数模型提出的数据属性。例如，/orders?fields=id,orderDate,total。

API 应根据消费者的要求提供对 multiple 数据格式的支持。例如，/orders/1234.json 返回 JSON 格式的数据。

根据设备及其支持 HTTP 动词的有限能力，您可能希望使用以下方法提供对 HTTP 方法的支持：

REST 服务在适当时为每个公开的方法使用基于角色的成员资格，并提供独立启用 GET、POST、< code class="literal">PUT 和 DELETE 基于任意数量的特定角色。

通常，应该在 API 网关级别处理。您不应该将此作为服务的一部分来处理。

由于业务或技术原因，服务库存可能会随时间而变化。它可能不可以同时替换对旧端点的所有引用。

通过采用这种设计实践，服务端点的消费者可以适应服务库存的重构。它会自动将访问过时端点标识符的服务消费者引用到当前标识符：

HTTP 本身支持使用 3xx 状态代码和标准标头组合的端点重定向模式：

服务消费者可能会以一种不向后兼容的方式更改他们的要求。一项服务可能必须同时支持新老消费者，而不必为每种消费者引入特定功能。

作为其调用的一部分，服务可以指定在运行时协商的服务能力接受或返回的特定内容和数据表示格式。服务契约是指多种标准化的媒体类型。

始终使用 SSL 来保护 URI。 SSL 确保有保障的加密通信，从而简化了身份验证工作——无需签署每个 API 请求。

这涵盖了 API 设计中的一些最佳实践。可以从 Google、Facebook 和 Amazon 如何定义其公共 API 并将其用作 API 设计的基础来学习。