服务计算—— RESTful 基础与基于资源的 API 实践

RESTful学习

• 微软API设计指南
• RESTful API 接口设计规范 | 示例
• 设计一个良好的restful风格API
• GitHub API v3
• RESTful API实践

具体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,
                                    }，
                                    …
                              ]
}