什么是好的 API 设计原则？【eolink翻译】

本文共计2897个文字，预计阅读时间需要12分钟。

对于完善其API及策略的团队来说，良好的API设计是一个常见的话题。API设计的重点在于无需赘述，核心在于精心设计。优秀的API设计包括：更佳的开发人员体验、更快的文档编写以及更佳的开发人员体验和更快的文档编写。

对于试图完善其 API 策略的团队来说，良好的 API 设计是一个经常出现的话题。

API 设计的重要性相信不需要赘述，精心设计的 API 的好处包括：更好开发人员体验、更快的文档编制以及更高的 API 使用率。

那么好的API设计到底是什么？这篇文章将详细介绍一些设计 RESTful API 的最佳实践。

| 精心设计的 API 的特征

一般来说，一个有效的 API 设计将具有以下特点：

*** 易于阅读和使用。**一个设计良好的 API 通常都易于使用，并且它的资源和相关操作可以被不断使用它的开发人员快速记住。

*** 难以滥用。**实现和集成具有良好设计的 API 是一个直截了当的过程，出现代码编写不正确的可能性会更小。它具有信息性反馈，并且不会强迫 API 的最终使用者遵守严格的规范。

*** 完整而简洁。**最后，完整的 API 能让开发人员针对公开的数据制作成熟的应用程序。大多数 API 设计人员和开发人员会在现有 API 的基础上逐步构建，使应用程序的完整性随时间推移而提高。这是每个拥有 API 的工程师或公司在努力实现的目标。

接下来的部分会以照片共享应用程序为例，说明一些概念。该应用程序允许用户上传照片，用这些照片的拍摄地点和描述与之相关的情绪的主题标签来表述。

| 集合、资源及其 URL

了解资源和集合

资源是 REST 概念的基础，它是一个非常重要的对象，可以被自身引用。资源具有数据、与其他资源的关系以及对其进行操作以允许访问和操作相关信息的方法。

一组资源称为一个集合。集合和资源的内容取决于组织机构和使用者的要求。