良好设计的API = 快乐的程序员 ?。 应用程序接口（API）是一种接口，它让应用程序可以轻松地使用另一个应用程序的数据和资源，API 对于一个产品或公司的成功至关重要。 如果没有它，你将不得不设计和开发自己的地图数据库。这样的话，在地图上显示一个位置需要花费多少时间？ 为什么要使用 API？ 在大多数实际场景中，数据模型 已经存在，但由于我们将讨论 API 设计最佳实践，我将从头开始说起。 数据建模与结构化 以 API 为中心对您的数据进行建模，是设计易于创建、维护和更新 API 的第一步 在设计 API 时，尽量考虑使用通用的术语，而不是使用内部的复杂业务术语，因为这些术语在公司外可能不为人所知 这些就是设计 API 的最佳实践。它让你的 API 更健壮、简洁并易于与其他应用程序集成。 请记住。 良好设计的API = 快乐的程序员 ?。
Web API 近几年变得越来越火，而简洁的 API 设计在多后端系统交互应用中也变得尤为重要。通常，会使用 RESTful API 来作为我们的 Web API 。 本文介绍了几种简洁 RESTful API 设计的最佳实践。 offset=10&limit=5 API 版本化 版本号使用简单的序号，并避免点符号，如2.5等。 正确用法如下： /blog/api/v1 充分使用 HTTP 状态码来处理错误 HTTP状态码（HTTP Status Code）是用以表示网页服务器 HTTP 响应状态的3位数字代码。 在设计 API 处理错误时，应该充分使用 HTTP 状态码，而不是简单的抛出个 “500 – Internal Server Error（内部服务器错误）” 所有的异常都应该有个错误的 payload
云服务器CVM、轻量应用服务器1.5折续费券等您来抽！
背景 目前互联网上充斥着大量的关于RESTful API（为了方便，以后API和RESTful API 一个意思）如何设计的文章，然而却没有一个”万能“的设计标准：如何鉴权？API格式如何？ 因为一旦发布，对外发布的API将会很难改变。 在给SupportedFu设计API的时候，我试图以实用的角度来解决上面提到的问题。 我希望可以设计出容易使用，容易部署，并且足够灵活的API，本文因此而生。 API设计的基本要求 网上的很多关于API设计的观点都十分”学院派“，它们也许更有理论基础，但是有时却和现实世界脱轨（因此我是自由派）。 所以我这篇文章的目标是从实践的角度出发，给出当前网络应用的API设计最佳实践（当然，是我认为的最佳了~），如果觉得不合适，我不会遵从标准。
参考github的api，总结一份实践经验，方便以后设计api查阅。 ? 使用https 考虑api的安全性，建议使用https访问。 证书可使用let’s encrypt的免费证书。 api访问地址与版本 访问地址使用统一的api前缀，或者使用二级域名，版本号建议显式的放在url中。 例如： https://www.iian.xyz/api/v1/users 交互结构 尽量采用json，提供替他类型的内容，使用accept声明可响应格式。 客户端使用content-type来标记使用的格式。 url设计 操作针对资源进行，使用url来代表资源，使用http请求方法来指明进行的操作。 根据执行情况，选择对应的状态码进行返回。可以使用自定义的状态码，但是也应该同时指明响应的状态码。具体的响应状态码含义可以，可以访问这个网站。
作者：Philipp Hauer 项目资源的URL应该如何设计？用名词复数还是用名词单数？一个资源需要多少个URL？用哪种HTTP方法来创建一个新的资源？可选参数应该放在哪里？ 哪些不涉及资源操作的URL呢？实现分页和版本控制的最好方法是什么？因为有太多的疑问，设计RESTful API变得很棘手。 在这篇文章中，我们来看一下RESTful API设计，并给出一个最佳实践方案。 不要这么设计： /getAllEmployees /getAllExternalEmployees /createEmployee /updateEmployee 更好的设计： GET /employees 将版本号放在URL中是必需的。如果您有不兼容和破坏性的更改，版本号可以让你更容易的发布API。发布新API时，只需增加版本号中的数字。
项目资源的URL应该如何设计？用名词复数还是用名词单数？一个资源需要多少个URL？用哪种HTTP方法来创建一个新的资源？可选参数应该放在哪里？那些不涉及资源操作的URL呢？ 实现分页和版本控制的最好方法是什么？因为有太多的疑问，设计RESTful API变得很棘手。在这篇文章中，我们来看一下RESTful API设计，并给出一个最佳实践方案。 这让你的API更简洁，URL数目更少。 不要这么设计： /getAllEmployees /getAllExternalEmployees /createEmployee /updateEmployee 更好的设计： GET /employees 将版本号放在URL中以是必需的。如果您有不兼容和破坏性的更改，版本号将让你能更容易的发布API。发布新API时，只需在增加版本号中的数字。
使用API设计工具 11. 使用简单序数作为版本 12. 在你的响应体中包括总资源数 13. 接受limit和offset参数 14. 获取字段查询参数 15. 不要在URL中通过认证令牌 16. 在这个微服务的世界里，后端API的一致性设计是必不可少的。 今天，我们将讨论一些可遵循的最佳实践。我们将保持简短和甜蜜——所以系好安全带，出发咯！ 首先介绍一些术语 任何API设计都遵循一种叫做“面向资源设计”的原则： 资源：资源是数据的一部分，例如：用户 集合：一组资源称为集合，例如：用户列表 URL：标识资源或集合的位置，例如：/user 1. 使用API设计工具 有许多好的API设计工具用于编写好的文档，例如： API蓝图：https://apiblueprint.org/ Swagger：https://swagger.io/ 拥有良好而详细的文档可以为 API使用者带来良好的用户体验。
RESTful是目前比较流行的接口路径设计规范，基于HTTP，一般使用JSON方式定义，通过不同HttpMethod来定义对应接口的资源动作，如：新增（POST）、删除（DELETE）、更新（PUT、PATCH 路径设计 在RESTful设计规范内，每一个接口被认为是一个资源请求，下面我们针对每一种资源类型来看下API路径设计。 路径设计的注意事项如下所示： 资源名使用复数 资源名使用名词 路径内不带特殊字符 避免多级URL 新增资源 请求方式 示例路径 POST https://api.yuqiyu.com/v1/users 针对不同的状态码我们要做出不同的反馈，下面我们先来看一个常见的参数异常错误响应设计方式： # 发起请求 curl -X POST -H 'Content-Type: application/json' timestamp 请求响应的时间戳 总结 RESTful是API的设计规范，并不是所有的接口都应该遵循这一套规范来设计，不过我们在设计初期更应该规范性，这样我们在后期阅读代码时根据路径以及请求方式就可以了解接口的主要完成的工作
这篇最佳实践文章面向对创建 RESTful Web 服务感兴趣的开发人员，这些服务提供跨多个服务套件的高可靠性和一致性；遵循这些准则；服务定位于内部和外部客户快速、广泛、公开采用。 这是一个完整的图表，可以轻松理解 REST API 的原理、方法和最佳实践。 现在，让我们从每个盒子的原理开始详细说明它。 最佳实践 现在，让我们换个角度来了解 REST 的基本最佳实践，这是每个工程师都应该知道的。 保持简单和细粒度：创建模拟系统底层应用程序域或系统数据库架构的 API。 资源命名：当资源命名正确时，API 是直观且易于使用的。做得不好，同样的 API 会让人感觉很笨拙，并且难以使用和理解。RESTful API 适用于消费者。 为您的客户设计，而不是为您的数据设计。 - 复数：普遍接受的做法是始终在节点名称中使用复数形式，以保持您的 API URI 在所有 HTTP 方法中保持一致。
大家好，我是小富~ 在这个微服务的世界里，后端API的一致性设计是必不可少的。 今天，我们将讨论一些可遵循的最佳实践。我们将保持简短和甜蜜——所以系好安全带，出发咯！ 首先介绍一些术语 任何API设计都遵循一种叫做“面向资源设计”的原则： 资源：资源是数据的一部分，例如：用户 集合：一组资源称为集合，例如：用户列表 URL：标识资源或集合的位置，例如：/user 1. 使用API设计工具 有许多好的API设计工具用于编写好的文档，例如： API蓝图：https://apiblueprint.org/ Swagger：https://swagger.io/ 拥有良好而详细的文档可以为 API使用者带来良好的用户体验。 应该：http://api.domain.com/v1/shops/3/products 始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。 12.
关于 restful api 本身以及设计原则，我陆陆续续也看过很多的文章和书籍，在读过原文后，感觉文中指出的 13 点最佳实践还是比较全面的且具有参考意义的，因此翻译出来分享给大家。 避免在 URI 中使用动词 如果你理解了第 1 条最佳实践所传达的意思，那么你现在就会明白不要将动词放入 REST API 的 URI 中。 采用 REST API 定制化的框架 作为最后一个最佳实践，让我们来探讨这样一个问题：你如何在 API 的实施中，实践最佳实践呢？ 因此，你必须采取额外的步骤来实施 API 中的最佳实践，但大多数情况下，由于懒惰或者时间紧张等因素，意味着你不会投入过多精力在这些方面 —— 然后给你的用户提供了一个古怪的 API 端点。 在各种语言中，许多专门用于构建 REST API 服务的新框架已经出现了，它们可以帮助你在不牺牲生产力的情况下，轻松地完成工作，同时遵循最佳实践。
数据建模与结构化 编写面向资源的 API RESTful 接口 API 版本控制 了解主要和次要更新 分页 ---- 前言 良好设计的API = 快乐的程序员 。 例如，Google Maps API 可以让你在 app 或 Web 应用中使用 Google Maps。如果没有它，你将不得不设计和开发自己的地图数据库。 API 设计最佳实践，我将从头开始说起。 API 的第一步 在设计 API 时，尽量考虑使用通用的术语，而不是使用内部的复杂业务术语，因为这些术语在公司外可能不为人所知。 这些就是设计 API 的最佳实践。它让你的 API 更健壮、简洁并易于与其他应用程序集成。 请记住。
数据建模与结构化 编写面向资源的 API RESTful 接口 API 版本控制 了解主要和次要更新 分页 ---- 前言 良好设计的API = 快乐的程序员 。 例如，Google Maps API 可以让你在 app 或 Web 应用中使用 Google Maps。如果没有它，你将不得不设计和开发自己的地图数据库。 API 设计最佳实践，我将从头开始说起。 API 的第一步 在设计 API 时，尽量考虑使用通用的术语，而不是使用内部的复杂业务术语，因为这些术语在公司外可能不为人所知。 这些就是设计 API 的最佳实践。它让你的 API 更健壮、简洁并易于与其他应用程序集成。 请记住。 良好设计的API = 快乐的程序员 。
Web API已经在最近几年变成重要的话题，一个干净的API设计对于后端系统是非常重要的。 通常我们为Web API使用RESTful设计，REST概念分离了API结构和逻辑资源，通过Http方法GET, DELETE, POST 和 PUT来操作资源。 下面是进行RESTful Web API十个最佳实践，能为你提供一个良好的API设计风格。 消费者一个选择字段的能力，这会降低网络流量，提高API可用性。 offset=5&limit=5>; rel="prev", 8.版本化你的API 使得API版本变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5. 一般在Url后面使用?
RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。 它的大原则容易把握，但是细节不容易做对。 本文总结 RESTful 的设计细节，介绍如何设计出易于理解和使用的 API。 ? 一、URL 设计 1.1 动词 + 宾语 RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。 ", "detail": { "surname": "This field is required." } } 3.3 提供链接 API 的使用者未必知道，URL 是怎么设计的。 对于用户来说，不需要记住 URL 设计，只要从 api.github.com 一步步查找就可以了。 HATEOAS 的格式没有统一规定，上面例子中，GitHub 将它们与其他属性放在一起。
在参考了GitHub API设计和大量博客文章后总结了一下RESTful API的设计，分享如下。 因为按照RESTful架构可以充分的利用HTTP协议带给我们的各种功能，算是对HTTP协议使用的最佳实践，还有一点就是可以使软件架构设计更加清晰，可维护性更好，但是并不是所有情况都需要完全遵守REST原则 对于安全方法，它仍然可能改变服务器上的内容或资源，但这必须不导致不同的表现形式。 有关HTTP常用方法幂等性和安全性如下： ? RESTful API设计规则： 1. 最佳做法是用固定的错误码来表示校验失败，然后在额外的errors字段中提供错误的细节，像这样： { "code" : 1024, "message" : "Validation Failed", Hypermedia API的设计被称为HATEOAS。
思维导图摘要 一、 RESTful API 设计的 6 项基本原则 重点： 本节给出了在设计 RESTful API 接口时需要遵循的基本原则。 统一接口 无状态 可缓存 C/S 架构 分层系统 按需编码（可选） 二、 实战小贴士 本节给出了有关 RESTful API 接口设计技巧速查表，可助你快速了解如何设计出最佳的 API 接口。 四、 API 命名规范 重点： 本节讲解如何设计出优秀的 API 接口，满是干货实例。 五、 实战指南 本小节主要讲解 API 设计时会面对的技术问题，包括但不限于版本号设计、用户认证、缓存、时间和日期处理等问题。 六、 资料 福利：有关 RESTful API 教程和相关知识点资料可以从这里获取。 导图 在线版 RESTful 服务最佳实践 思维导图。 图片预览版 ?
资源编排 TIC为您提供易用、高效、安全的基础架构管理平台。平台使用声明型语言，兼容众多优秀的开源社区工具，同时提供代码编辑和视图编辑两种模式，有效降低学习成本和使用难度。TIC 使用代码版本管理的方式管理基础架构，保障基础设施的构建、管理和迁移的可靠性和安全性。
扫码关注腾讯云开发者
领取腾讯云代金券
云服务器
测试服务 WeTest
文件存储
命令行工具
SSL 证书
