首页 > 其他分享 >Restful API规范

Restful API规范

时间:2024-11-07 16:23:32浏览次数:1  
标签:url fields 数据类型 规范 API user 服务器 Restful id

Restful API规范
restful api是用于在前端与后台进行通信的一套规范。使用这个规范可以让前后端开发变得更加轻松。以下将讨论这套规范的一些设计细节。

协议:
采用http或者https协议。

数据传输格式:
数据之间传输的格式应该都使用json,而不使用xml。

url链接:
url链接中,不能有动词,只能有名词。并且对于一些名词,如果出现复数,那么应该在后面加s。

比如:获取文章列表,应该使用/articles/,而不应该使用/get_article/

HTTP请求的方法:
GET:从服务器上获取资源。
POST:在服务器上新创建一个资源。
PUT:在服务器上更新资源。(客户端提供所有改变后的数据)
PATCH:在服务器上更新资源。(客户端只提供需要改变的属性)
DELETE:从服务器上删除资源。
示例如下:

GET /users/:获取所有用户。
POST /user/:新建一个用户。
GET /user/id/:根据id获取一个用户。
PUT /user/id/:更新某个id的用户的信息(需要提供用户的所有信息)。
PATCH /user/id/:更新某个id的用户信息(只需要提供需要改变的信息)。
DELETE /user/id/:删除一个用户。
状态码:
状态码 原生描述 描述
200 OK 服务器成功响应客户端的请求。
400 INVALID REQUEST 用户发出的请求有错误,服务器没有进行新建或修改数据的操作
401 Unauthorized 用户没有权限访问这个请求
403 Forbidden 因为某些原因禁止访问这个请求
404 NOT FOUND 用户发送的请求的url不存在
406 NOT Acceptable 用户请求不被服务器接收(比如服务器期望客户端发送某个字段,但是没有发送)。
500 Internal server error 服务器内部错误,比如出现了bug
Flask-Restful插件
通过pip install flask-restful即可安装。

如果使用Flask-Restful,那么定义视图函数的时候,就要继承自flask_restful.Resource类,然后再根据当前请求的method来定义相应的方法。比如期望客户端是使用get方法发送过来的请求,那么就定义一个get方法。类似于MethodView。示例代码如下:

from flask import Flask,render_template,url_for
from flask_restful import Api,Resource

app = Flask(name)

用Api来绑定app

api = Api(app)

class IndexView(Resource):
def get(self):
return {"username":"donghao"}

api.add_resource(IndexView,'/',endpoint='index')
注意事项:

endpoint是用来给url_for反转url的时候指定的。如果不写endpoint,那么将会使用视图的名字的小写来作为endpoint。
add_resource的第二个参数是访问这个视图函数的url,这个url可以跟之前的route一样,可以传递参数。并且还有一点不同的是,这个方法可以传递多个url来指定这个视图函数。
参数解析:
Flask-Restful插件提供了类似WTForms来验证提交的数据是否合法的包,叫做reqparse。以下是基本用法:

parser = reqparse.RequestParser()
parser.add_argument('username',type=str,help='请输入用户名')
args = parser.parse_args()
add_argument可以指定这个字段的名字,这个字段的数据类型等。以下将对这个方法的一些参数做详细讲解:

default:默认值,如果这个参数没有值,那么将使用这个参数指定的值。
required:是否必须。默认为False,如果设置为True,那么这个参数就必须提交上来。
type:这个参数的数据类型,如果指定,那么将使用指定的数据类型来强制转换提交上来的值。
choices:选项。提交上来的值只有满足这个选项中的值才符合验证通过,否则验证不通过。
help:错误信息。如果验证失败后,将会使用这个参数指定的值作为错误信息。
trim:是否要去掉前后的空格。
其中的type,可以使用python自带的一些数据类型,也可以使用flask_restful.inputs下的一些特定的数据类型来强制转换。比如一些常用的:

url:会判断这个参数的值是否是一个url,如果不是,那么就会抛出异常。
regex:正则表达式。
date:将这个字符串转换为datetime.date数据类型。如果转换不成功,则会抛出一个异常。
输出字段:
对于一个视图函数,你可以指定好一些字段用于返回。以后可以使用ORM模型或者自定义的模型的时候,他会自动的获取模型中的相应的字段,生成json数据,然后再返回给客户端。这其中需要导入flask_restful.marshal_with装饰器。并且需要写一个字典,来指示需要返回的字段,以及该字段的数据类型。示例代码如下:

class ProfileView(Resource):
resource_fields = {
'username': fields.String,
'age': fields.Integer,
'school': fields.String
}

@marshal_with(resource_fields)
def get(self,user_id):
    user = User.query.get(user_id)
    return user

在get方法中,返回user的时候,flask_restful会自动的读取user模型上的username以及age还有school属性。组装成一个json格式的字符串返回给客户端。

重命名属性:

很多时候你面向公众的字段名称是不同于内部的属性名。使用 attribute可以配置这种映射。比如现在想要返回user.school中的值,但是在返回给外面的时候,想以education返回回去,那么可以这样写:

resource_fields = {
'education': fields.String(attribute='school')
}
默认值:

在返回一些字段的时候,有时候可能没有值,那么这时候可以在指定fields的时候给定一个默认值,示例代码如下:

resource_fields = {
'age': fields.Integer(default=18)
}
复杂结构:

有时候想要在返回的数据格式中,形成比较复杂的结构。那么可以使用一些特殊的字段来实现。比如要在一个字段中放置一个列表,那么可以使用fields.List,比如在一个字段下面又是一个字典,那么可以使用fields.Nested。以下将讲解下复杂结构的用法:

class ProfileView(Resource):
resource_fields = {
'username': fields.String,
'age': fields.Integer,
'school': fields.String,
'tags': fields.List(fields.String),
'more': fields.Nested({
'signature': fields.String
})
}

标签:url,fields,数据类型,规范,API,user,服务器,Restful,id
From: https://www.cnblogs.com/zhaoshuo1/p/18532662

相关文章

  • ndis.sys 是 Windows 操作系统中的一个关键系统文件,属于 网络驱动接口规范(NDIS,Network
    ndis.sys是Windows操作系统中的一个关键系统文件,属于网络驱动接口规范(NDIS,NetworkDriverInterfaceSpecification)的一部分。它是一个用于管理网络驱动程序和网络接口卡(NIC)之间通信的核心组件,主要负责网络设备驱动与操作系统的接口。具体来说,ndis.sys充当了操作系统与网络......
  • [C#] 代码规范
    一、接口化多使用依赖注入,减少静态类的使用。例如工具类的日志、文件压缩、服务器时间、相机等等,以日志为例,定义日志的接口,日志的实现可能是log4net、Serilog、NLog,也可能是自行实现,定义接口ILog,使用依赖注入获取单例,后期切换新的日志实现时,只需要实现日志接口并注入到IOC容......
  • 96_api_intro_metadata_middleschool
    全国中学基础信息API数据接口基础数据,高校高考,提供全国初级高级中学基础数据,定时更新,多维度筛选。1.产品功能2024年数据已更新;提供最新全国中学学校基本信息;包含全国初级中学与高等中学;总计近10万条全国中学精准数据;每月一次数据自动更新校正;包含学校各类属性信息......
  • 95_api_intro_websitetools_readability
    网页可读内容抽取API数据接口智能提取文章关键元素信息,智能抽取,多种元素信息。1.产品功能智能提取网页可阅读内容;提供网页可阅读内容的HTML代码;支持传递网页HTML或网页URL参数;支持多种元素信息抽取,包括文章标题、作者、文字方向、语言、内容、内容(不包含HTML标......
  • 94_api_intro_stock_stockbidask
    A股买卖盘口数据API数据接口不同价格级别买卖数量和报价,股票交易数据,盘口分析。1.产品功能实时更新股票盘口数据;支持A股所有股票;支持按股票代码查询;高效、稳定的数据获取体验;毫秒级查询性能;数据持续更新与维护;全接口支持HTTPS(TLSv1.0/v1.1/v1.2/v1.3);全......
  • 93_api_intro_finance_optionsrealtime
    期权实时行情数据最新价格、交易量、交易额等信息,期权行情实时数据,市场交易数据。1.产品功能实时更新期权市场数据;覆盖主要期权合约;支持多种数据参数,包括价格、交易量、持仓量等;提供详细的市场分析和数据解读;高效、稳定的数据获取体验;秒级查询性能;数据持续更新与维护;......
  • 92_api_intro_stock_stockcncashflow
    A股个股资金流API数据接口全量股票资金流数据,全量A股数据,最长30日历史数据1.产品功能支持所有A股资金流数据查询;每日定时更新数据;支持多达30日历史数据查询;超高的查询效率,数据秒级返回;数据持续更新与维护;全接口支持HTTPS(TLSv1.0/v1.1/v1.2/v1.3);全面兼容......
  • 91_api_intro_stock_stockcncashflowrank
    A股个股资金流排行API数据接口全量股票资金流排名,多时间区间,全量A股数据。1.产品功能支持所有A股资金流数据查询;每日定时更新数据;支持多时间段查询;超高的查询效率,数据秒级返回;数据持续更新与维护;全接口支持HTTPS(TLSv1.0/v1.1/v1.2/v1.3);全面兼容AppleATS;......
  • 90_api_intro_stock_currencyexchange
    国际货币汇率API数据接口支持多种货币对,每日精准汇率,多币种支持。1.产品功能支持多种货币汇率查询;支持部分加密货币汇率查询;数据为每日更新汇率数据;可一次查询源货币代码对应所有目标货币汇率;数据持续更新与维护;全接口支持HTTPS(TLSv1.0/v1.1/v1.2/v1.3);全面......
  • 89_api_intro_websitetools_whois
    域名Whois查询API数据接口多类型域名支持,精准Whois数据,实时数据。1.产品功能支持国际、国内域名Whois查询;每小时定时更新基础数据库;提供精准、高效的Whois查询;返回可查询最详细的域名相关信息;秒级查询性能,支持高并发;数据持续更新与维护;全接口支持HTTPS(TLS......