在 Total Control 即将发布的 6.7.0 版本中，新增的脚本 REST API 将是一大亮点。REST API 支持任意脚本语言在 Total Control 脚本运行，如 Java,JS,Spython,C,C++ 等，同时可以将 Total Control 运用于 Android 和 Ios 系统手机，Windows 或 Macos 操作系统的电脑等，客户可以通过任意网络，连接多个 Total Control 客户端，实现成百上千的手机群控。
很多用户对于手机驱动这个名称特别陌生，认为手机驱动特别复杂，实际上并不复杂，手机驱动程序是为了保证 PC 与手机之间建立连接的通道，因为 Total Control 主要是基于 USB 方式连接和控制，因此连接 Total Control 之前首先需要保证 PC 能与手机建立正常的通信，因此安装手机驱动是非常重要的步骤。
方舟：生存进化手机版什么时候上线？方舟：生存进化是由独立工作室Wildcard旗下由虚幻引擎4打造的生存类开放世界游戏，故事主要讲一群人醒来便出现在神秘海滩，为了生存而探索远古开放世界，玩家需要通过合作/竞技来获取生活必需品。众所周知，由蜗牛代理的方舟生存进化online电脑版已于日上线。手机版的方舟：生存进化官方称将于2018年春季登陆中国区IOS/安卓平台。
明日之后什么时候上线公测？网易自研的开放世界生存 MMO 手游明日之后即将在 5 月 10 日开启限量测试，本次测试为删档不收费测试，并且 IOS 和安卓均有测试资格。这次算是第三次测试，本轮测试完成之后不出意外就离正式公测时间不久了。现在即可到官网预约测试资格。在 SegmentFault，学习技能、解决问题
每个月，我们帮助 1000 万的开发者解决各种各样的技术问题。并助力他们在技术能力、职业生涯、影响力上获得提升。
标签：至少1个，最多5个
Restful API 设计规范
使用的名词而不是动词
不应该使用动词：
/getAllResources
/createNewResources
/deleteAllResources
GET方法和查询参数不能改变资源状态:
如果要改变资源的状态，使用PUT、POST、DELETE。下面是错误的用GET方法来修改user的状态：
GET /users/711?activate
GET /users/711/activate
Rest的核心原则是将你的API拆分为逻辑上的资源。这些资源通过HTTP被操作(GET,POST,PUT,DELETE)
我们定义资源ticket、user、group:
GET /tickets # 获取ticket列表
GET /tickets/12 # 查看某个具体的ticket
POST /tickets # 新建一个ticket
PUT /tickets/12 #新建ticket 12
DELETE /tickets/12 # 删除ticket 12
只需要一个endpoint：/tickets，再也没有其他什么命名规则和url规则了。
一个可以遵循的规则是：虽然看起来使用复数来描述某一个资源看起来特别扭，但是统一所有的endpoint，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。
处理关联：
GET /tickets/12/messages # 获取ticket 12的message列表
GET /tickets/12/messages/5 #获取ticket 12的message 5
POST /tickets/12/messages 创建ticket 12的一个message
PUT /tickets/12/messages/5 更新ticket 12的message 5
DELETE /tickets/12/messages/5 删除ticket 12的message 5
避免层级过深的URI
/ 在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。
过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使用查询参数代替路劲中的实体导航，如GET /animals?zoo=1&area=3。
结果过滤，排序，搜索
url最好越简短越好，对结果过滤、排序、搜索相关的功能都应该通过参数实现。
过滤：例如你想限制GET /tickets 的返回结果：只返回那些open状态的ticket， GET /tickets?state=open 这里的state就是过滤参数。
排序：和过滤一样，一个好的排序参数应该能够描述排序规则，而不和业务相关。复杂的排序规则应该通过组合实现。排序参数通过 , 分隔，排序参数前加 - 表示降序排列。
GET /tickets?sort=-priority #获取按优先级降序排列的ticket列表
GET /tickets?sort=-priority,created_at #获取按优先级降序排列的ticket列表，在同一个优先级内，先创建的ticket排列在前面。
搜索：有些时候简单的排序是不够的。我们可以使用搜索技术来实现
GET /tickets?q=return&state=open&sort=-priority,create_at # 获取优先级最高且打开状态的ticket，而且包含单词return的ticket列表。
限制API返回值的域
有时候API使用者不需要所有的结果，在进行横向限制的同时（例如值返回API结果的前十个），还应该可以进行纵向限制，并且这个功能能有效的提高网络带宽使用率和速度。可以使用fields查询参数来限制返回的域例如：
GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at
Response不要包装
response 的 body直接就是数据，不要做多余的包装。错误实例：
"success":true,
"data":{"id":1, "name":"xiaotuan"}
更新和创建操作应该返回资源
在POST操作以后，返回201created 状态码，并且包含一个指向新资源的url作为返回头。
是蛇形命名还是驼峰命名？如果使用json那么最好的应该是遵守JavaScript的命名方法-驼峰命名法。Java、C# 使用驼峰，python、ruby使用蛇形。
默认使用pretty print格式，开启gzip
开启pretty print返回结果会更加友好易读，而且额外的传输也可以忽略不计。如果忘了使用gzip那么传输效率将会大大减少，损失大大增加。
GitHub v3S实践经验
1.Current Version
通过Accept字段来区分版本号，而不是在url中嵌入版本号：
Accept: application/vnd.github.v3+json
Summary Representation
当你请求获取某一资源的列表时，响应仅返回资源的属性子集。有些属性对API来说代价是非常高的，出于性能的考虑，会排除这些属性。要获取这些属性，请求"detailed" representation。
Example：当你获取仓库的列表时，你获得的是每个仓库的summary representation。
GET /orgs/octokit/repos
Detailed Representation
当你获取一个单独的资源时，响应会返回这个资源的所有属性。
Example：当你获取一个单独的仓库，你会获得这个仓库的detailed representation。
GET /repos/octokit/octokit.rb
3.Parameters
许多API都带有可选参数。对于GET请求，任何不作为路径构成部分的参数都可以通过HTTP查询参数传入。
GET https://api.github.com/repos/vmg/redcarpet/issues?state=closed
在这个例子中，'vmg' 和 'redcarpet' 作为 :owner 和 :repo 的参数，而 :state 作为查询参数。
对于POST、PATCH、PUT和DELETE的请求，不包含在URL中的参数需要编码成JSON传递，且 Content-Type为 'application/json'。
Root Endpoint
你可以对根节点GET请求，获取根节点下的所有API分类。
Client Errors
有三种可能的客户端错误，在接收到请求体时：
1 发送非法JSON会返回 400 Bad Request.
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}
2 发送错误类型的JSON值会返回 400 Bad Request.
HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Body should be a JSON object"}
3 发送无效的值会返回 422 Unprocessable Entity.
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
"message": "Validation Failed",
"errors": [
"resource": "Issue",
"field": "title",
"code": "missing_field"
我们可以告诉发生了什么错误，下面是一些可能的验证错误码：
Error Name
Description
资源不存在
missing_field
资源必需的域没有被设置
域的格式非法
already_exists
另一个资源的域的值和此处的相同，这会发生在资源有唯一的键的时候
HTTP Redirects
API v3在合适的地方使用HTTP重定向。客户端应该假设任何请求都会导致重定向。重定向在响应头中有一个 Location 的域，此域包含了资源的真实位置。
HTTP Verbs
API v3力争使用正确的HTTP动词来表示每次请求。
Description
对任何资源仅请求头信息
使用部分的JSON数据更新资源
取代资源或资源集合
Hypermedia
很多资源有一个或者更多的 *_url 属性指向其他资源。这意味着服务端提供明确的URL，这样客户端就不必要自己构造URL了。
Pagination
请求资源列表时会进行分页，默认每页30个。当你请求后续页的时候可以使用 ?page 参数。对于某些资源，你可以通过参数 ?per_page自定义每页的大小。
curl 'https://api.github.com/user/repos?page=2&per_page=100'
需要注意的一点是，页码是从1开始的，当省略参数 ?page 时，会返回首页。
Basics of Pagination
关于分页的其他相关信息在响应的头信息的 Link 里提供。比如，去请求一个搜索的API，查找Mozilla的项目中哪些包含词汇addClass :
curl -I "https://api.github.com/search/code?q=addClass+user:mozilla"
头信息中Link字段如下:
Link: &https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2&; rel="next", &https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34&; rel="last"
rel="next" 表示下一页是 page=2。也就是说，默认情况下所有的分页请求都是从首页开始。rel="last" 提供更多信息，表示最后一页是34。即我们还有33页的信息包含addClass。
总之，我们应该依赖于Link提供的信息，而不要尝试自己去猜或者构造URL。
Navigating through the pages
既然已经知道会接收多少页面，我们可以通过页面导航来消费结果。我们可以通过传递一个page参数，例如跳到14页：
curl -I "https://api.github.com/search/code?q=addClass+user:mozilla&page=14"
这是头信息中Link字段：
Link: &https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15&; rel="next",
&https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34&; rel="last",
&https://api.github.com/search/code?q=addClass+user%3Amozilla&page=1&; rel="first",
&https://api.github.com/search/code?q=addClass+user%3Amozilla&page=13&; rel="prev"
我们会获得更多的信息，rel="first"表示首页，rel="prev"表示前一页的页码。通过这些信息，我们可以构造一个UI界面让用户在first、previous、next、last之间进行跳转。
Rate Limiting
对于认证的请求，可以每小时最多请求5000次。对于没有认证的请求，限制在每小时60次请求。
检查返回的HTTP头，可以看到当前的速率限制：
curl -i https://api.github.com/users/whatever
HTTP/1.1 200 OK
Server: GitHub.com
Date: Thu, 27 Oct :42 GMT
Content-Type: application/ charset=utf-8
Content-Length: 1219
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 48
X-RateLimit-Reset:
header头信息告诉你当前的速率限制状态：
Header Name
Description
X-RateLimit-Limit
当前用户被允许的每小时请求数
X-RateLimit-Remaining
在当前发送窗口内还可以发送的请求数
X-RateLimit-Reset
按当前速率发送后，发送窗口重置的时间
一旦你超过了发送速率限制，你会收到一个错误响应：
HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug :41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset:
"message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
"documentation_url": "https://developer.github.com/v3/#rate-limiting"
User Agent Required
所有的API请求必须包含一个有效的 User-Agent 头。请求头不包含User-Agent的请求会被拒绝。
Conditional requests
大多数响应都会返回一个 ETag 头。很多响应也会返回一个 Last-Modified 头。你可以使用这些头信息对这些资源进行后续请求，分别使用 If-None-Match 和 If-Modified-Since头。如果资源没有发生改变，服务器端会返回 304 Not Modified。
Enchant REST API 实践经验
Limited HTTP Clients
如果你使用的HTTP客户端不支持PUT、PATCH、DELETE方法，发送一个POST请求，头信息里包含X-HTTP-Method-Override字段，它的值是实际需要的动词。
$ curl -u email:password https://site.enchant.com/api/v1/users/543abc \
-H "X-HTTP-Method-Override: DELETE"
Rate Limiting
所有响应的头部包含描述当前限流状态的字段:
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 99
Rate-Limit-Used: 1
Rate-Limit-Reset: 20
Rate-Limit-Limit - 当前时间段内允许的总的请求数
Rate-Limit-Remaining - 当前时间段内还剩余的请求数
Rate-Limit-Used - 本次所使用的请求数
Rate-Limit-Reset - 重置所需秒数
如果速率限制被打破，API会返回 429 Too Many Requests 的状态码。在这种情况下，你的应用不应该再发送任何请求直到 Rate-Limit-Reset 所规定的时间过去。
Field Filtering
你可以自己限制响应返回的域。只需要你传递一个 fields 参数，用逗号分隔所需要的域，比如：
GET /api/v1/users?fields=id,first_name
所有返回一个集合的URL，都会提供count统计所有结果的个数。要获取count值需要加一个 count=true 的参数。count会在消息头中的Total-Count 字段中返回。
GET /api/v1/tickets?count=true
Total-Count: 135
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 98
Rate-Limit-Used: 2
Rate-Limit-Reset: 20
Content-Type: application/json
... results ...
count表示所有现存结果的数量，而不是此次响应返回的结果的数量。
Enveloping
如果你的HTTP客户端难以读取状态码和头信息，我们可以将所有都打包进响应消息体中。我们只需要传递参数 envelope=true，而API会始终返回200的HTTP状态码。真正的状态码、头信息和响应都在消息体中。
GET /api/v1/users/does-not-exist?envelope=true
"status": 404,
"headers": {
"Rate-Limit-Limit": 100,
"Rate-Limit-Remaining": 50,
"Rate-Limit-Used": 0,
"Rate-Limit-Reset": 25
"response": {
"message": "Not Found"
其他如 分页、排序等，enchant的设计规范和GitHub v3大致相同，不在赘述。
1 收藏&&|&&21
你可能感兴趣的文章
8 收藏，3.7k
1 收藏，1.1k
3 收藏，1.3k
写的不错，很有帮助
写的不错，很有帮助
总结得很全面，如果能给参考链接都发出来就更好了
总结得很全面，如果能给参考链接都发出来就更好了
分享到微博？
我要该，理由是：
在 SegmentFault，学习技能、解决问题
每个月，我们帮助 1000 万的开发者解决各种各样的技术问题。并助力他们在技术能力、职业生涯、影响力上获得提升。一男的并排站我边上，就感觉他在那打量我，看看上，又低头看看下，这是不是鄙视我的心理？_百度知道
一男的并排站我边上，就感觉他在那打量我，看看上，又低头看看下，这是不是鄙视我的心理？
我有更好的答案
何必那么在意别人怎么看你,是你自己太敏感了。别人爱怎么看就让他看去,自己的生活自己过。
为您推荐：
其他类似问题
换一换
回答问题，赢新手礼包
个人、企业类
违法有害信息,请在下方选择后提交
色情、暴力
我们会通过消息、邮箱等方式尽快将举报结果通知您。云栖社区(yq.aliyun.com)为您免费提供restful相关的问答和话题，云栖社区以分享专业、优质、高效的技术为己任，帮助技术人快速成长与发展!