构建API的7个技巧

18-10-19 banq
         

截至2018年,企业越来越依赖API来为其客户服务。微服务和无服务器架构正变得越来越普遍,并且创建了更多的所需API集成点,以确保竞争优势和业务可见性。API应该从头开始设计,并考虑到这些需求。在本文中,我将讨论有助于实现这些目标的API的七个设计技巧。(我应该注意,这些见解是基于我为移动客户端构建API的经验,但可更广泛地应用于任何类型的API设计。

1.将API视为产品

开发的期初关键因素是产品概念。它定义了独立的实体,为市场提供有用的功能和好处。设计和实施易于消费,可扩展,正确记录和保护的API并不是一项容易的任务,而且不会在过程中产生强烈的责任感和所有权。因此,将API被视为一个公平,完整的董事会,积压和冲刺计划是公平的。此外,还需要指定产品负责人,以便向敏捷团队传达理想API的愿景。开发人员和测试人员必须制定计划以使用API​​最佳实践,并避免常见错误。最终产品需要从第一天开始生产。

2.使用API​​规范框架

API框架旨在标准化跨行业的开发流程。通常,它们由一系列工具组成,涵盖从概念到生产的整个开发生命周期。虽然在开发API时坚持使用OpenAPI / Swagger这样的规范更为明确,但它提供了更好的工具互操作性。每个人都喜欢自动化,并且每次代码更改时都能够生成文档,SDK和UI交互点非常有用。如果您关心标准并希望在描述API时提供传统工具,那么这是一个非常可靠的选项,可以提前还清。

3.使用版本控制策略

您的API是您的产品,随着业务需求的变化,它会随着时间的推移而发展。作为产品,它具有特定版本,因此客户期望得到正确的响应。更改已发布和使用的API接口是一个定时炸弹。你想要的最后一件事是在没有客户知道的情况下引入重大变化。对于移动应用程序尤其如此,用户可能仍然在其手机上安装旧版本。有多种方法可以在API上实施版本控制信息。大多数API设计者都选择将版本信息放在URL中,因为它很实用。例如,以下URL表示customer的资源端点:/ API / V1 /customer坚持适用于业务和可用工具的版本策略非常重要。稍后,如果您决定更改版本,则更容易提供警告,更新和其他机制。

4.使用过滤和分页

开发API时的一个常见错误是没有提供过滤或分页结果的方法。当您公开返回可随时间变化的项目列表的API时,您需要建立分页策略。原因很简单。客户端,尤其是移动客户端,无法一次查看数百个列表项,因此您可以显示前10个(例如)。如果您的API返回每个请求的整个数据库列表,则会浪费大量资源并且性能会大幅下降。现代框架提供了一种分页结果的方法,但也可以自定义自己的结果。常见的方法是在查询中使用LIMIT和OFFSET语句。例如,请参阅此MySQL语句以返回总结果的一部分:SELECT * form customer LIMIT 5,10此语句将从数据库中检索第6-16行,以便您可以提供JSON响应,该响应根据LIMIT参数提供指向该查询的第一页,下一页,上一页和最后一页的链接:

 

// _links
{
  “first”:“ / api / v1 / customers ?page = 1 “,
   ”prev“:” / api / v1 / customers ?page = 1 “,
   ”next“:” / api / v1 / customers ?page = 3 “,
   ”last“:” / api / v1 / customers ?page = 9 “ 
}

5.使用REST和HATEOAS

REST是一种经过验证且经过实战考验的架构方法,用于设计Web服务,它独立于任何底层协议。因此,它非常适合设计API。通过使用REST原则,您可以应用一些设计注意事项,例如:

  • 将端点视为具有传统命名方案的资源。例如,如果要公开订单列表,则公开以下端点:

GET / api / v1 /order如果要查找特定订单,您将提供ID参数:GET / api / v1 / orders / 1这具有几个优点,例如更好的均匀性,可读性和一致性。

  • 促进无状态交易。这些有助于使服务更具可扩展性,因为它们不具有在客户端和服务器通信之间保持状态的硬耦合约束。
  • 在HATEOAS的帮助下,无需事先了解内部URI方案,即可在整个资源集中轻松导航。它通过提供一组相关链接来增强每个资源的响应模型,这样在不查找规范或其他元数据服务的情况下更容易与API交互。HATEOAS的一个好格式是HAL规范。例如,这是对特定文章资源的HAL响应,公开了记者的相关链接:

{
   “_ links”:{
     “Self”:{
         “href”:“ / api / v1 / articles / 1 ”
    },
    “ / rels / reporter”:[
      {
        “href”:“ / api / v1 / reporter / 1121 ” 
        “fullName”:“John  Doe”
      },
      {
        “href”:“ / api / v1 / reporter / 192 ” 
        “fullName”:“Alice  Jansen”
      }
    ]
  }
}

6.保护您的终端你不应该忽视安全。任何违规行为都可能产生灾难性后果,并可能导致严重的法律问题。需要在开发过程的早期建立安全控制,理想情况下,您的API需要由外部供应商进行评估。在CIA安全的黑社会适用下列要求:

  • 安全性通过添加适当的身份验证控件来实现,这些身份验证控件为您的系统提供了一种了解谁正在访问信息或站点的方法。OAuth2JWT提供了一种实用且安全的方法来提供此功能。必须在所有公共端点使用HTTPS以确保安全通信。
  • 集成性是通过使用实现访问控制和授权策略,以防止未经授权的用户数据的篡改。基于角色的授权提供了一个很好的选择。
  • 可用性通过建立实现速率限制,部分反应和缓存,以防止API资源或无限循环取下来,甚至服务器的广泛使用。

7.使用监控和报告虽然开发和测试API在此过程中起着重要作用,但真正的工作并不止于此。甚至在将代码部署到生产之前,您需要继续提供支持。如果出现问题,需要通过可操作的信息通知合适的人员,以便以任何必要的方式作出回应。这是开发API时的主动方法。如果你把事情放在一边,那么当端点问题出现时,你可以防止灾难性的失败。