学习Django-rest-framework必读: 什么是Web API及如何设计一个良好的restful风格的API

其他 2018-10-26 19:59:54 阅读次数: 0

很多读者对django-rest-framework非常感兴趣, 小编我也开始准备用几篇长文专门介绍这个框架。这个框架的主要用途是为Django网站提供一个良好的符合restful规范的web接口API。在学习该框架之前，你需要对Web API和RESTful有最基本的了解。小编我搜集了篇精华文章，大家可以先看看吧。

什么是Web API?

现代网络应用Web APP或大型网站一般是一个后台，然后客户端却各种各样(iOS, android, 浏览器), 而且客户端的开发语言与后台的开发语言也不一样。这时需要后台能够提供可以跨平台跨语言的一种标准的资源或数据(如Json格式)供前后端沟通，这就是Web API(网络应用程序结口)的作用了。通过Web API，服务器可以对接各种客户端（浏览器，移动设备）。Web API在收到不同客户端的请求后，一般返回Json或xml格式的数据。

什么是RESTful?

REST是“REpresentational State Transfer”的缩写，可以翻译成“表现状态转换”。REST是一种软件架构风格，如果你的web接口API是符合REST规范的，那么你的API就是restful的。RESTful Web API采用面向资源的架构，所以在设计之初首先需要考虑的是有哪些资源可供操作的，并采用URI来作为资源的标识。作为资源标识的URI最好具有“可读性”，因为具有可读性的URI更容易被使用。这样不同种类的客户端都可以通过HTTP方法对这些资源进行操作。

以下内容为转载。该文介绍了restful API规范，重点介绍了URI的设计。

  • 原文地址: https://mp.weixin.qq.com/s?__biz=MzA5NDg3MjAwMQ==&mid=2457102222&idx=1&sn=9d2d0c7aa5d4e496317d909dfdd2023c&chksm=87c8cf20b0bf4636187c09fe6c486b82e05c9ea27edb7a587946ebc14048f28d3c07a8ad02d8&token=988915080&lang=zh_CN#rd

  • 作者: 梁桂钊

  • 原文标题: 良好的API设计指南

版本号

在 RESTful API 中，API 接口应该尽量兼容之前的版本。但是，在实际业务开发场景中，可能随着业务需求的不断迭代，现有的 API 接口无法支持旧版本的适配，此时如果强制升级服务端的 API 接口将导致客户端旧有功能出现故障。实际上，Web 端是部署在服务器，因此它可以很容易为了适配服务端的新的 API 接口进行版本升级，然而像 Android 端、IOS 端、PC 端等其他客户端是运行在用户的机器上，因此当前产品很难做到适配新的服务端的 API 接口，从而出现功能故障，这种情况下，用户必须升级产品到最新的版本才能正常使用。

为了解决这个版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留版本号，并同时兼容多个版本。

 

  1. 【GET】  /v1/users/{user_id}  // 版本 v1 的查询用户列表的 API 接口

  2. 【GET】  /v2/users/{user_id}  // 版本 v2 的查询用户列表的 API 接口

现在，我们可以不改变版本 v1 的查询用户列表的 API 接口的情况下，新增版本 v2 的查询用户列表的 API 接口以满足新的业务需求，此时，客户端的产品的新功能将请求新的服务端的 API 接口地址。虽然服务端会同时兼容多个版本，但是同时维护太多版本对于服务端而言是个不小的负担，因为服务端要维护多套代码。这种情况下，常见的做法不是维护所有的兼容版本，而是只维护最新的几个兼容版本，例如维护最新的三个兼容版本。在一段时间后，当绝大多数用户升级到较新的版本后，废弃一些使用量较少的服务端的老版本API 接口版本，并要求使用产品的非常旧的版本的用户强制升级。

注意的是，“不改变版本 v1 的查询用户列表的 API 接口”主要指的是对于客户端的调用者而言它看起来是没有改变。而实际上，如果业务变化太大，服务端的开发人员需要对旧版本的 API 接口使用适配器模式将请求适配到新的API 接口上。

资源路径

RESTful API 的设计以资源为核心，每一个 URI 代表一种资源。因此，URI 不能包含动词，只能是名词，且个URI结尾不能加"/"。注意的是，形容词也是可以使用的，但是尽量少用。一般来说，不论资源是单个还是多个，API 的名词要以复数进行命名。此外，命名名词的时候，要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持一致。例如，一个查询系统标签的接口可以进行如下设计。

【GET】  /v1/tags/{tag_id}

同时，资源的路径应该从根到子依次如下。

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

我们来看一个“添加用户的角色”的设计，其中“用户”是主资源，“角色”是子资源。

【POST】  /v1/users/{user_id}/roles/{role_id} // 添加用户的角色

有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}

举个例子，“密码修改”这个接口的命名很难完全使用名词来构建路径，此时可以引入 action 命名。

【PUT】  /v1/users/{user_id}/password/actions/modify // 密码修改

请求方式

可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中，GET 用于查询单个资源或一个资源集合，POST 用于创建资源，PUT 用于更新服务端的资源的全部信息，PATCH 用于更新服务端的资源的部分信息，DELETE 用于删除服务端的资源。

这里，笔者使用“用户”的案例进行回顾通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。

 

  1. 【GET】          /users                # 查询用户信息列表

  2. 【GET】          /users/1001           # 查看某个用户信息

  3. 【POST】         /users                # 新建用户信息

  4. 【PUT】          /users/1001           # 更新用户信息(全部字段)

  5. 【PATCH】        /users/1001           # 更新用户信息(部分字段)

  6. 【DELETE】       /users/1001           # 删除用户信息

查询参数

RESTful API 接口应该提供参数，过滤返回结果。其中，offset 指定返回记录的开始位置。一般情况下，它会结合 limit 来做分页的查询，这里 limit 指定返回记录的数量。

【GET】  /{version}/{resources}/{resource_id}?offset=0&limit=20

同时，orderby 可以用来排序，但仅支持单个字符的排序，如果存在多个字段排序，需要业务中扩展其他参数进行支持。

【GET】  /{version}/{resources}/{resource_id}?orderby={field} [asc|desc]

为了更好地选择是否支持查询总数，我们可以使用 count 字段，count 表示返回数据是否包含总条数，它的默认值为 false。

【GET】  /{version}/{resources}/{resource_id}?count=[true|false]

上面介绍的 offset、 limit、 orderby 是一些公共参数。此外，业务场景中还存在许多个性化的参数。我们来看一个例子。

【GET】  /v1/categorys/{category_id}/apps/{app_id}?enable=[1|0]&os_type={field}&device_ids={field,field,…}

注意的是，不要过度设计，只返回用户需要的查询参数。此外，需要考虑是否对查询参数创建数据库索引以提高查询性能。

状态码

使用适合的状态码很重要，而不应该全部都返回状态码 200，或者随便乱使用。这里，列举笔者在实际开发过程中常用的一些状态码，以供参考。

状态码 描述
200 请求成功
201 创建成功
400 错误的请求
401 未验证
403 被拒绝
404 无法找到
409 资源冲突
500 服务器内部错误

异常响应

当 RESTful API 接口出现非 2xx 的 HTTP 错误码响应时，采用全局的异常结构响应信息。

 

  1. HTTP/1.1 400 Bad Request

  2. Content-Type: application/json

  3. {

  4. "code": "INVALID_ARGUMENT",

  5. "message": "{error message}",

  6. "cause": "{cause message}",

  7. "request_id": "01234567-89ab-cdef-0123-456789abcdef",

  8. "host_id": "{server identity}",

  9. "server_time": "2014-01-01T12:00:00Z"

  10. }

请求参数

在设计服务端的 RESTful API 的时候，我们还需要对请求参数进行限制说明。例如一个支持批量查询的接口，我们要考虑最大支持查询的数量。

 

  1. 【GET】     /v1/users/batch?user_ids=1001,1002      // 批量查询用户信息

  2. 参数说明

  3. - user_ids: 用户ID串，最多允许 20 个。

此外，在设计新增或修改接口时，我们还需要在文档中明确告诉调用者哪些参数是必填项，哪些是选填项，以及它们的边界值的限制。

 

  1. 【POST】     /v1/users                             // 创建用户信息

  2. 请求内容

  3. {

  4. "username": "lgz",                 // 必填, 用户名称, max 10

  5. "realname": "梁桂钊",               // 必填, 用户名称, max 10

  6. "password": "123456",              // 必填, 用户密码, max 32

  7. "email": "[email protected]",     // 选填, 电子邮箱, max 32

  8. "weixin": "LiangGzone",            // 选填，微信账号, max 32

  9. "sex": 1                           // 必填, 用户性别[1-男 2-女 99-未知]

  10. }

响应参数

针对不同操作，服务端向用户返回的结果应该符合以下规范。

 

  1. 【GET】     /{version}/{resources}/{resource_id}      // 返回单个资源对象

  2. 【GET】     /{version}/{resources}                    // 返回资源对象的列表

  3. 【POST】    /{version}/{resources}                    // 返回新生成的资源对象

  4. 【PUT】     /{version}/{resources}/{resource_id}      // 返回完整的资源对象

  5. 【PATCH】   /{version}/{resources}/{resource_id}      // 返回完整的资源对象

  6. 【DELETE】  /{version}/{resources}/{resource_id}      // 状态码 200，返回完整的资源对象。

  7. // 状态码 204，返回一个空文档

如果是单条数据，则返回一个对象的 JSON 字符串。

 

  1. HTTP/1.1 200 OK

  2. {

  3. "id" : "01234567-89ab-cdef-0123-456789abcdef",

  4. "name" : "example",

  5. "created_time": 1496676420000,

  6. "updated_time": 1496676420000,

  7. ...

  8. }

如果是列表数据，则返回一个封装的结构体。

 

  1. HTTP/1.1 200 OK

  2. {

  3. "count":100,

  4. "items":[

  5. {

  6. "id" : "01234567-89ab-cdef-0123-456789abcdef",

  7. "name" : "example",

  8. "created_time": 1496676420000,

  9. "updated_time": 1496676420000,

  10. ...

  11. },

  12. ...

  13. ]

  14. }

一个完整的案例

最后，我们使用一个完整的案例将前面介绍的知识整合起来。这里，使用“获取用户列表”的案例。

 

  1. 【GET】     /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 获取用户列表

  2. 功能说明：获取用户列表

  3. 请求方式：GET

  4. 参数说明

  5. - keyword: 模糊查找的关键字。[选填]

  6. - enable: 启用状态[1-启用 2-禁用]。[选填]

  7. - offset: 获取位置偏移，从 0 开始。[选填]

  8. - limit: 每次获取返回的条数，缺省为 20 条，最大不超过 100。 [选填]

  9. 响应内容

  10. HTTP/1.1 200 OK

  11. {

  12. "count":100,

  13. "items":[

  14. {

  15. "id" : "01234567-89ab-cdef-0123-456789abcdef",

  16. "name" : "example",

  17. "created_time": 1496676420000,

  18. "updated_time": 1496676420000,

  19. ...

  20. },

  21. ...

  22. ]

  23. }

  24. 失败响应

  25. HTTP/1.1 403 UC/AUTH_DENIED

  26. Content-Type: application/json

  27. {

  28. "code": "INVALID_ARGUMENT",

  29. "message": "{error message}",

  30. "cause": "{cause message}",

  31. "request_id": "01234567-89ab-cdef-0123-456789abcdef",

  32. "host_id": "{server identity}",

  33. "server_time": "2014-01-01T12:00:00Z"

  34. }

  35. 错误代码

  36. - 403 UC/AUTH_DENIED    授权受限

下面我们会慢慢讲解Django-rest-framework, 欢迎关注我们的微信公众号。

大江狗

2018.9.20

猜你喜欢

转载自blog.csdn.net/weixin_42134789/article/details/82782259
今日推荐
《美国对全球网络空间安全与发展的威胁和破坏》报告发布
火速冲上 GitHub 热榜 —— 开源编程语言、框架哪有这么可爱？
北京人形机器人创新中心发布全球首个纯电驱拟人奔跑的全尺寸人形机器人“天工”
LFOSSA 源来如此公开课 | 掌握云原生未来：CNCF 认证全面攻略与备考秘籍
国产云输入法——仅华为无云端数据上传安全问题
周排行
Python环境安装与基础语法（1）——计算机基础知识
IMU预积分
ADAS中的LDW、FCW、BSD、LCA、ACC、AEB、APA、DMS代表的含义
B站笔试两道题
skyeye arm 硬件虚拟机环境的搭建
Web前端静态页面示例
数组-合并排序数组 II-简单
springcloud之版本问题启动报错
面向对象-------------匿名对象(六)
输入URL到页面呈现中间发生了什么？
每日归档
更多
2024-04-30(1)
2024-04-29(40)
2024-04-28(0)
2024-04-27(56)
2024-04-26(39)
2024-04-25(22)
2024-04-24(36)
2024-04-23(26)
2024-04-22(39)
2024-04-21(0)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022