创建 REST API 的最佳入门教程(2)

当我们参考收集的资源时(list all:列出所有 和add one:新增一个),这将会经常用到。当你用到一些特殊的资源的时候,你就会给URL增加一个id,这个URL在你想要“view”,“edit”和“delete”特殊资源的时候会被使用。

嵌套资源

如果说,我们的部件有很多用户使用,URL的结构又将会是怎样的呢?

列出所有用户

GET /widgets/123/users

新增一个用户

POST /widgets/123/users

Data:

name =Andrew

嵌套资源在URL里是完全兼容的,但是超过两层嵌套就不是很好的方法了。其实这根本不需要,因为你完全可以以ID的形式参考到那些嵌套资源,总比嵌套在父类中好。例如:

/widgets/123/users/456/sports/789

这可以替换为:

/users/456/sports/789

甚至可以替换成这样:

/sports/789

HTTP 状态码

REST的另一重要部分就是为既定好请求的类型来响应正确的状态码。如果你对HTTP状态码陌生,以下是一个简易总结。当你请求HTTP时,服务器会响应一个状态码来判断你的请求是否成功,然后客户端应如何继续。以下是四种不同层次的状态码:

2xx = Success(成功)

3xx = Redirect(重定向)

4xx = User error(客户端错误)

5xx = Server error(服务器端错误)

以下是一些最重要的状态码:

请求成功的状态码:

200 – OK (默认的)

201 – Created(已创建)

202 – Accepted (已接受:常用语删除请求)

客户端错误状态码:

400 –请求出错(语法格式有误或服务器无法理解此请求)

401 – 未授权(需要登录)

404 – 找不到 (找不到所请求的文件或脚本)

405 – 不允许此方法(错误的 HTTP方法)

409 – 冲突 (IE尝试以PUT请求创建相同的资源时)

API响应格式

当你请求HTTP时,你可以请求你想要接收的格式。例如,请求一个网页,你想以HTML的格式请求,或者如果你想要下载一张图片,返回格式应该是图片的格式。然而,响应请求格式是服务器的职责。

如今,JSON 已经快速发展成为REST API选择的格式,它有一个轻量级的、可读性又很高的语法,以致其很容易操作。所以,当使用我们API的用户按他们想要的格式发出请求和指定JSON时。

GET /widgets

Accept: application/json

我们的API将会以JSON的格式返回一批部件:

[

{

id:123,

name:'Simple Widget'

},

{

id:456,

name:'My other widget'

}

]

要是用户请求一个我们没有实现的方法的格式时,我们又该怎么办呢?你大可以抛出一些错误的类型。但我建议你将JSON格式作为你的标准响应格式,因为这是开发者想要的格式。没理由去支持其他的格式,除非你已经有一个可支持的API。

创建一个REST API

事实上,创建一个REST API是超出此教程范围的,因为它是有特定语言的。但我将以Ruby(一种为简单快捷的面向对象编程而创的脚本语言)的方式给出一个简易例子,它使用一个叫Sinatra的类库(不懂得可以自行百度)。

require'sinatra'

require'JSON'

require'widget'#our imaginary widget model

#list all

get'/widgets'do

Widget.all.to_json

end

# view one

get'/widgets/:id'do

widget=Widget.find(params[:id])

returnstatus404ifwidget.nil?

widget.to_json

end

# create

post'/widgets'do

widget=Widget.new(params['widget'])

widget.save

status201

end

# update

put'/widgets/:id'do

widget=Widget.find(params[:id])

returnstatus404ifwidget.nil?

widget.update(params[:widget])

widget.save

status202

end

delete'/widgets/:id'do

widget=Widget.find(params[:id])

returnstatus404ifwidget.nil?

widget.delete

status202

end

API授权认证

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/15779.html