濮阳之窗:RESTful设计中的常见疑问

admin 4个月前 (05-16) 科技 33 0

最近写了几个有关RESTful的API相关内容,也谈谈对常见问题的自己的明了。

1.什么是RESTful

详情可以看http://www.ruanyifeng.com/blog/2011/09/restful.html。

简朴可以这么明了,使用URI去代表资源,使用HTTP VERB(GET PUT等)对资源的操作。

2.为什么要用RESTful

使用RESTful,优点有许多,也利便差其余请求方去请求数据。枚举两个:

  • HTTP方式语义都很明确,使用GET去获得数据,使用DELETE去删除数据。
  • 返回值也是很明确的HTTP RESPONSE,200就是执行乐成,400就是请求错误。

那是不是每一个API都需要使用REST气概呢?我以为不是,这要看团队、项目而定,不必一味强求。

3.在URI资源地址中使用v1之类的版本号符不符合RESTful?

这个涉及到RESTful的版本治理,常见的方式有这么几种。

URL Path

/api/v1/helloworld

许多公然的API地址内里,都带有version信息,若是非要去扣符不符合RESTful,估量要吵起来。然则这个方式很便捷、明确,挪用方一看就明了,也没有分外的工作量去做。不外瑕玷也很明显,由于已经限制死了版本号在URI中,无法实现同一个URI地址版本的天真切换,也不能指定默认版本。

Query String

/api/helloworld?api-version=1.0

这个方式没有改变URI自己,然则需要挪用方去分外处置Query string,不外幸亏这个可以指定默认的。

Media Types

POST api/helloworld HTTP/1.1
host: localhost
content-type: text/plain;v=2.0
content-length: 12

Hello there!

在Content-Type内里添加v=x.x的版本号也是一个不错的选择,可以实现QueryString类似的功效。

有一些现成的库可以辅助我们实现上面的Versioning方式,常见的是aspnet-api-versioning

4.什么是平安性?

无论请求多少次,服务器的状态(资源)都不会改变,那么这个方式就是平安的。

GET HEAD都应该设计成平安的。

5.什么是幂等性?

无论对资源操作多少次,服务器资源效果总是一样的,那么这个方式就是幂等的。注重这里的说法,是服务器的资源效果是一样的,不代表请求的返回效果是一样的。好比DELETE请求,它是幂等的,然则删除一个资源许多次的情形(多次执行DELETE api/student/1,第一次返回乐成,第二次返回失败,然则不影响服务器上对应的纪录已经删除的状态。

GET、HEAD、PUT和DELETE请求都应该设计成是幂等的。

6.新增数据用POST照样PUT?

资源新增可以用POST也可以用PUT,然则设计上有几个区别。

幂等性

PUT是幂等的,POST不是,若是设计上需要不应用幂等性,那么使用POST。好比POST计数器的应用,每次POST,计数器都增进1。

请求目的

POST一样平常请求的是资源聚集,而PUT一样平常请求是一个详细的资源。

PUT /students/{id}
POST /students

这也意味着,语义上,POST是请求在聚集中新增资源。

主动权

  • 若是id不是由挪用方天生的情形下,需要指定的资源ID的PUT方式就欠好实现了。这种情形,使用POST到资源更合理,主动权在服务器方,服务器建立资源之后,返回201携带新天生的工具URI。
  • 若是id是由挪用方天生的情形下(好比一些硬件装备发生的数据),使用POST和PUT都可以,然则PUT有幂等性,显得加倍明确,这种时刻我一样平常选择使用PUT。

笼罩

PUT语义是要求笼罩的,若是数据已经存在,就必须笼罩。POST的没有这个要求,可以有其余行为。

7.修改数据应该使用PUT照样PATCH?

不一定,要看情形。PUT是笼罩性的修改,而PATCH是追加性的修改。

  • 使用PUT的时刻,需要将数据完整返回,若是有的字段没有赋值,那么将保持为默认值。
  • PUT是幂等的,PATCH不是,因此多次执行PUT请求,效果是一样的;执行PATCH有可能不一样。
{
"value": 
    {
        "id": "235314",
        "deviceId": "123",
        "type": "低温"
    }
}

若是发送的数据只含有deviceId,执行PUT之后,资源酿成:

{
"value": 
    {
        "id": "235314",
        "deviceId": "111"
    }
}

执行PATCH,资源酿成:

{
"value": 
    {
        "id": "235314",
        "deviceId": "111",
        "type": "低温"
    }
}

8.没有数据返回204照样404?

问题:

若是请求一个这样的资源

GET api/sutudents/homework

在没有homework的情形下应该返回HTTP 204 NoContent照样返回HTTP 404 NotFound?

乍看一眼,以为似乎都差不多,没内容和没找到横竖都是没有。但深入想想,照样有很大的区其余。

  1. 404返回的更倾向于表述不存在的性子,而204返回表述没有内容,也就是存在,然则没有内容。
  2. 4xx返回表述大要是请求有问题,而2xx返回表述大要是请求没有问题。

以是,对于上面的问题,这么明了,若是homework是已经建立的资源,然则内容为空,那么返回204是可以的,然则若是homework这个器械就不存在,那么应该返回404。

个人认为直接返回200,携带对应的空内容会比204要对挪用方加倍友好,至少和有数据的情形是一样处置。

9.写给前端

有许多前端同砚需要服务器返回牢固的乐成信息(好比200)或者错误信息(好比400)。但HTTP CODE许多,一个一个判断效率很低,幸亏HTTP CODE是分类的,好比2xx大要是OK的,4xx都是有问题的。可以通过CODE / 100 == 2之类的方式去大要确定返回的状态 。

,

阳光在线手机版下载

阳光在线(原诚信在线官网)现已开放阳光在线手机版、阳光在线电脑客户端下载。阳光在线娱乐游戏公平、公开、公正,用实力赢取信誉。

Allbet声明:该文看法仅代表作者自己,与本平台无关。转载请注明:濮阳之窗:RESTful设计中的常见疑问

网友评论

  • (*)

最新评论

站点信息

  • 文章总数:437
  • 页面总数:0
  • 分类总数:8
  • 标签总数:970
  • 评论总数:117
  • 浏览总数:3358