使用 swagger 生成Flask RESTful API

什么是 RESTful

什么是REST

REST(英文:Representational State Transfer,又称具象状态传输)是Roy Thomas Fielding博士于2000年在他的博士论文[1] 中提出来的一种万维网软件架构风格,目的是便于不同软件/程序在网络(例如互联网)中互相传递信息。

REST 的核心是可编辑的资源及其集合,用符合 Atom 文档标准的 Feed 和 Entry 表示。每个资源或者集合有一个惟一的 URI。系统以资源为中心,构建并提供一系列的 Web 服务。

在 REST 中,开发人员显式地使用 HTTP 方法,对系统资源进行创建、读取、更新和删除的操作:

  • 使用 POST 方法在服务器上创建资源

  • 使用 GET 方法从服务器检索某个资源或者资源集合

  • 使用 PUT 方法对服务器的现有资源进行更新

  • 使用 DELETE 方法删除服务器的某个资源

如果一个架构符合REST原则,就可以称它为RESTful架构

RESTful API 设计定义

以下是几个RESTful API的几个概念。

  • 资源(Resource):系统上的所有事物都被抽象为资源(一篇文章,一张照片,一段语音)

  • 集合(Collection):一组资源的合辑称为集合(几篇文章,几张照片)

  • 路径(Endpoint):路径又称”终点“,表示API的具体网址(每个网址代表一种资源)

那么一个设计良好的RESTful API应该遵循哪些原则呢?

协议

API与用户的通信协议总是使用HTTPs协议。

域名

应该尽量将API部署在专用域名,例如:

https://apis.gusibi.com

API地址和版本

在url中指定API版本。比如:

https://apis.gusibi.com/v1

以资源为中心设计URL

资源是RESTful API的核心元素,所有的操作都是针对特定资源进化的。而资源就是URL表示的,所以简洁、清晰、结构化的URL设计是至关重要的。在RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。我们来看一下 Github 的例子:

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

使用正确的Method

对于资源的具体操作类型,使用HTTP method 表示。以下是常用的HTTP方法。

  • GET:从服务器取出资源

  • POST:在服务器新建一个资源

  • PUT:在服务器更新资源(客户端提供改变后的完整资源

  • PATCH:在服务器更新资源(客户端只提供改变了属性)

  • DELETE:从服务器删除资源

还是使用 github 的例子:

GET /repos/:owner/:repo/issues
GET /repos/:owner/:repo/issues/:number
POST /repos/:owner/:repo/issues
PATCH /repos/:owner/:repo/issues/:number
DELETE /repos/:owner/:repo

正确的过滤信息(filtering)

如果记录数量很多,服务器不能都将他们返回给用户。API应该提供参数,过滤返回结果。

下边是一些是、常见的参数。

  • ?limit=10: 指定返回记录的数量

  • ?offset=10:指定返回记录的开始位置

  • ?page=2&per_page=100::指定第几页,以及每页的记录数。

  • ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。

  • ?animal_type_id=1:指定筛选条件

选择合适的状态码

HTTP 应答中,需要带一个很重要的字段:status code。它说明了请求的大致情况,是否正常完成、需要进一步处理、出现了什么错误,对于客户端非常重要。状态码都是三位的整数,大概分成了几个区间:

2XX:请求正常处理并返回3XX:重定向,请求的资源位置发生变化4XX:客户端发送的请求有错误5XX&#x

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值