RESTful学习
具体API设计
版本号
v1.0.0
前提概要
所有的API访问都是通过HTTPS进行的,并通过https://api.blog.com(虚构)进行访问。所有数据都以JSON的形式发送和接收。
空白字段被包含为null,而不是被忽略。
所有时间戳返回ISO 8601格式:
YYYY-MM-DDTHH:MM:SSZ
总结陈述
在获取资源列表时,响应只包含该资源的属性子集。也就是说,当请求一堆资源时,只返回这些资源的部分信息(比如名称、内容摘要等等)。
在获取一个单一的资源时,响应包含这个资源的全部属性。
参数说明
许多API方法采用可选参数。对于GET请求,任何未在路径中指定为段的参数都可以作为HTTP查询字符串参数传递。
对于POST、PATCH、PUT和DELETE请求,URL中没有包含的参数应该用“application/ JSON”的内容类型编码为JSON。
操作示例
获取用户信息
GET /userMessage
Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
username | query | String | 用户名 |
Success
Code | Reason |
---|---|
200 - OK | 请求成功 |
Error
Code | Reason |
---|---|
401 - Unauthorized | 用户未登录 |
403 - Forbidden | 无权限访问访问 |
500- Internal Server Error | 服务器内部异常 |
Response Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
originalBlogCount | Body | Interger | 原创博客篇数 |
fansCount | Body | Interger | 粉丝数 |
applaudCount | Body | Interger | 获赞数 |
commentCount | Body | Interger | 评论数 |
visitorVolume | Body | Interger | 访问量 |
level | Body | Interger | 用户等级 |
weekRank | Body | String | 周排名 |
memberPoint | Body | Interger | 用户剩余积分 |
totalRank | Body | String | 总排名 |
recentArticles | Body | Array[String] | 最新文章 |
Response Example
{
“originalBlogCount”:27,
“fansCount”:1,
“applaudCount”:5,
“commentCount”:1,
“visitorVolume”:5386,
“level”:2,
“weekRank”:“6万+”,
“memberPoint”:326,
“totalRank”:“21万+”,
“recentArticles”:[“Unity3D——血条制作”, “服务计算——开发 web 服务程序”, “Unity3D 游戏编程——粒子系统”, “Unity游戏编程-——迷宫巡逻兵”, “Unity3d-learning 物理碰撞打飞碟小游戏” ]
}
获取文章列表
GET /user/Articles
Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
username | query | String | 用户名 |
articlesType | query | Bool | 是否是原创文章, true表示选择原创文章 |
Success
Code | Reason |
---|---|
200 - OK | 请求成功 |
Error
Code | Reason |
---|---|
401 - Unauthorized | 用户未登录 |
403 - Forbidden | 无权限访问访问 |
500- Internal Server Error | 服务器内部异常 |
Response Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
articlesList | Body | Array[JSON] | 文章列表 |
对每个文章的JSON信息,内部包含参数 articleName(文章名称)、isOriginal(是否是原创文章)、digest(文章摘要)、creationTime(文章创建时间)、pageview(文章阅读数)、commentsCount(评论数)。
Response Example
{
“articlesList”:[
{
“articleName”:“原创 Unity3D——血条制作”,
“isOriginal”:true,
“digest”:"文章目录游戏要求使用IMGUI实现血条使用UGUI实现血条两种实现的优缺点IMGUI实现UGUI实现预制的使用方法游戏要求分别使用 IMGUI 和 UGUI 实现使用 UGUI,血条是游戏对象的一个子元素,任何时候需要面对主摄像机分析两种实现的优缺点给出预制的使用方法使用IMGUI… ",
“creationTime”:“2019-11-20 22:29:21”,
“pageview”:2,
“commentsCount”:0,
},
{
“articleName”:“服务计算——开发 web 服务程序”,
“isOriginal”:true,
“digest”:文章目录开发Web服务程序任务目标熟悉 go 服务器工作原理编写一个简单 web 应用使用 curl 工具访问 web 程序对 web 执行压力测试开发Web服务程序任务目标熟悉 go 服务器工作原理基于现有 web 库,编写一个简单 web 应用类似 cloudgo。使用… ",
“creationTime”:“2019-11-13 20:06:33”,
“pageview”:6,
“commentsCount”:0,
},
…
]
}
选择文章置顶
PATCH /user/Articles/stick
Success
Code | Reason |
---|---|
200 - OK | 请求成功 |
Error
Code | Reason |
---|---|
400 - Bad Request | 无效请求内容,参数错误 |
401 - Unauthorized | 用户未登录 |
403 - Forbidden | 无权限访问访问 |
500- Internal Server Error | 服务器内部异常 |
Request Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
username | Body | String | 用户名 |
articleSerialNum | Body | Intereger | 选择置顶的文章序号(从0开始) |
Request Example
{
“username”:wangzh297,
“articleSerialNum”:1
}
Response Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
articlesList | Body | Array[JSON] | 文章列表 |
Response Example
{
“articlesList”:[
{
“articleName”:“服务计算——开发 web 服务程序”,
“isOriginal”:true,
“digest”:文章目录开发Web服务程序任务目标熟悉 go 服务器工作原理编写一个简单 web 应用使用 curl 工具访问 web 程序对 web 执行压力测试开发Web服务程序任务目标熟悉 go 服务器工作原理基于现有 web 库,编写一个简单 web 应用类似 cloudgo。使用… ",
“creationTime”:“2019-11-13 20:06:33”,
“pageview”:6,
“commentsCount”:0,
},
{
“articleName”:“原创 Unity3D——血条制作”,
“isOriginal”:true,
“digest”:"文章目录游戏要求使用IMGUI实现血条使用UGUI实现血条两种实现的优缺点IMGUI实现UGUI实现预制的使用方法游戏要求分别使用 IMGUI 和 UGUI 实现使用 UGUI,血条是游戏对象的一个子元素,任何时候需要面对主摄像机分析两种实现的优缺点给出预制的使用方法使用IMGUI… ",
“creationTime”:“2019-11-20 22:29:21”,
“pageview”:2,
“commentsCount”:0,
},…
]
}
删除文章
DELETE /user/Articles/delete
Success
Code | Reason |
---|---|
200 - OK | 请求成功 |
Error
Code | Reason |
---|---|
400 - Bad Request | 无效请求内容,参数错误 |
401 - Unauthorized | 用户未登录 |
403 - Forbidden | 无权限访问访问 |
500- Internal Server Error | 服务器内部异常 |
Request Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
username | Body | String | 用户名 |
articleSerialNum | Body | Intereger | 选择置顶的文章序号(从0开始) |
Request Example
{
“username”:wangzh297,
“articleSerialNum”:1
}
Response Parameters
参数名 | 所在域 | 类型 | 描述 |
---|---|---|---|
articlesList | Body | Array[JSON] | 文章列表 |
Response Example
{
“articlesList”:[
{
“articleName”:“原创 Unity3D——血条制作”,
“isOriginal”:true,
“digest”:"文章目录游戏要求使用IMGUI实现血条使用UGUI实现血条两种实现的优缺点IMGUI实现UGUI实现预制的使用方法游戏要求分别使用 IMGUI 和 UGUI 实现使用 UGUI,血条是游戏对象的一个子元素,任何时候需要面对主摄像机分析两种实现的优缺点给出预制的使用方法使用IMGUI… ",
“creationTime”:“2019-11-20 22:29:21”,
“pageview”:2,
“commentsCount”:0,
},
…
]
}