开发者社区> 范大脚脚> 正文

RESTful API URI 设计: 判断资源是否存在?

简介:
+关注继续查看

如果这个问题出现在 MVC 项目中,我想我们一般会这样设计:

public class ProductService
{
    public async Task<bool> IsExist(int userId, string productName)
    {
        ....
    }
}

看来没什么问题,的确也没什么问题,那如果把这部分代码搬到 ASP.NET WebAPI 项目中实现,会是怎样呢?我们来看一下:

public class ProductsController : ApiController
{
    [HttpGet]
    [Route("api/products/isexist/{userId}/{productName}")]
    public async Task<bool> IsExist(int userId, string productName)
    {
        ...
    }
}

我想你应该发现一些问题了,这种写法完全是 MVC 的方式,但并不适用于 WebAPI,主要有三个问题:

  • Route 定义混乱,完全违背 REST API URI 的一些设计原则。
  • Action 命名不恰当。
  • bool 返回值不合适。

对于上面的三个问题,我们分别来探讨下。

1. URI 设计

首先,我们知道在 REST API 中,URI 代表的是一种资源,它的设计要满足两个基本要求,第一名词而非动词,第二要能清晰表达出资源的含义,换句话说就是,从一个 URI 中,你可以很直接明了的知道访问的资源是什么,我们再来看我们设计的 URI:

api/products/isExist/{userId}/{productName}

这是什么鬼???这种设计完全违背 URI 原则,首先,我们先梳理一下,我们想要请求的资源是什么?没错,是产品(Products),但这个产品是某一个用户下的,所以用户和产品有一个上下级关系,访问产品首先得访问用户,这一点要在 URI 中进行体现,其次,我们是获取产品?还是判断产品是否存在?这个概念是不同的,产品的唯一标识和用户一样,都是 id,在 URI 的一般设计中,如果要访问某一唯一标识下的资源(比如 id 为 1 的 product),会这样进行设计:api/products/{id},HttpClient 请求中会用 HttpGet 方法(api/products/1),这样我们就可以获得一个 id 为 1 的 product,但现在的场景是,获取产品不通过唯一标识,而是通过产品名称,难道我们要这样设计:

api/products/{productName}

咋看之下,这样好像设计也没什么问题,但总觉得有些不对劲,比如如果再加一个产品大小,难道要改成这样:api/products/{productName}/{productSize},这种设计完全是不恰当的,上面说到,URI 代表的是一种资源,通过 URI 获取资源的唯一方式是通过资源的唯一标识,除此之外的获取都可以看作是对资源的查询(Query),所以,针对我们的应用场景,URI 的设计应该是这样(正确):

api/users/{userId}/products: api/users/1/products?productName=windows 10

上面的 URI 清晰明了的含义:查询 id 为 1 用户下名称为 windows 10 的产品。

2. Action 命名

对于 IsExist 的命名,如果没有很强的强迫症,其实也是可以接受的,因为 WebAPI 的 URI 并不会像 MVC 的 Route 设计那样,在访问的时候,URL 一般会默认 Action 的名字,所以,在 WebAPI Action 设计的时候,会在 Action 前面加一个 Route 属性,用来配置 URI,也就是说每一个 Action 操作会对应一个 URI 请求操作,这个请求操作也就是 HTTP 的常用方法。

如果我们想把 IsExist 改掉,那用什么命名会好些呢?先回忆一下,我们在使用 Visual Studio 创建 ASP.NET WebAPI 项目的时候,VS 会自动创建一些示例 Action,我们看看能不能从那里得到一些线索:

public class ValuesController : ApiController
{
    // GET api/values
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    // GET api/values/5
    public string Get(int id)
    {
        return "value";
    }

    // POST api/values
    public void Post([FromBody]string value)
    {
    }

    // PUT api/values/5
    public void Put(int id, [FromBody]string value)
    {
    }

    // DELETE api/values/5
    public void Delete(int id)
    {
    }
}

上面是 Values 资源的一些 Action 实现,我们可以看到,Action 的命名和 HTTP 方法一样,比如 Get 就是 Get,而不是 GetById,Get 是动词,表示它对资源的一种操作,具体是通过什么进行操作?在参数中可以很直观的进行反应,一般会在 HelpPage 中进行注释说明。

IsExist 的含义还是判断资源是否存在,其本质上来说就是去获取一个资源,也就是 Get 操作,所以,在 WebAPI Action 中对此的命名,我们直接使用 Get 会好一下,或者使用 Exist。

3. 请求返回

bool 一般是用在项目方法中的返回值,如果用在 HTTP 请求中,就不是很恰当了,我先贴出几篇文章:

上面除去第一篇文章,其他文章都是在讨论:检查一个资源是否存在,REST API 该如何设计(HTTP status code)?客户端获取服务的响应不是通过 bool,而是通过 HTTP 状态码,主要设计三个:404、204 和 200:

  • 404 is correct since the resource "/users/{username}" was Not Found.
  • If the resource exists but it is empty (as in "null") then you should return 204.
  • If the resource exists and contains any data then you should return 200.

204 和 404 有所不同的是,204 表示资源存在,但是为空,404 代表的是原始资源本身就不存在,并且通过唯一标识查询不到,而 204 更多的是表示,在一定条件下的资源不存在,但可以通过唯一标识查询到,所以如果资源不存在返回 204 不恰当,wikipedia 中 200 和 404 详细说明:

  • 200 OK - ... The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource.
  • 404 Not Found - The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

HTTP status code 简要说明:

  • 2xx codes Tell a UA that it did the right thing, the request worked. It can keep doing this in the future.(请求成功)
  • 3xx codes Tell a UA what you asked probably used to work, but that thing is now elsewhere. In future the UA might consider just going to the redirect.(请求很可能成功)
  • 4xx codes Tell a UA it did something wrong, the request it constructed isn't proper and shouldn't try it again, without at least some modification.(请求失败)
  • 5xx codes Tell a UA the server is broken somehow. But hey that query could work in the future, so there is no reason not to try it again. (except for 501, which is more of a 400 issue).(请求错误)

在上面文章中,有一段很有意思的对话(请略过翻译):

  • Alien: Computer, please tell me all planets that humans inhabit.(电脑,请告诉我所有适宜人类居住的星球。)
    Computer: 1 result found. Earth(查询到一个结果,地球)
  • Alien: Computer, please tell me about Earth.(电脑,请告诉我地球的信息。)
    Computer: Earth - Mostly Harmless.(地球-无害。)
  • Alien: Computer, please tell me about all planets humans inhabit, outside the asteroid belt.(电脑,请告诉我小行星带以外,所有适宜人类居住的星球。)
    Computer: 0 results found.(没有查询到结果。)
  • Alien: Computer, please destroy Earth.(电话,请毁灭地球。)
    Computer: 200 OK.(毁灭成功。)
  • Alien: Computer, please tell me about Earth.(电脑,请告诉我地球的信息。)
    Computer: 404 - Not Found(没有找到。)
  • Alien: Computer, please tell me all planets that humans inhabit.(电脑,请告诉我所有适宜人类居住的星球。)
    Computer: 0 results found.(没有找到。)
  • Alien: Victory for the mighty Irken Empire!(看不懂啥意思)

搜刮到的一张 HTTP status code 示意图(点击查看大图):

211601203965650.png

4. 最终代码

针对一开始的应用问题,最终完善代码:

public class ProductsController : ApiController
{
    [HttpGet]
    [Route("api/users/{userId}/products")]
    public async Task<HttpResponseMessage> Get(int userId, string productName)
    {
        if (true)
        {
            return Request.CreateResponse(HttpStatusCode.OK);
        }
        else
        {
            return Request.CreateResponse(HttpStatusCode.NotFound);
        }
    }
}

public class WebApiTest
{
    [Fact]
    public async Task Exists_Product_ByProductName()
    {
        using (var client = new HttpClient())
        {
            client.BaseAddress = new System.Uri(Base_Address);
            var response = await client.GetAsync("/api/users/1/products?productName=windows 10");
            //var requestMessage = new HttpRequestMessage(HttpMethod.Head, "/api/users/1/products?productName=windows 10");
            //var response = await client.SendAsync(requestMessage);//更好的调用方式,只请求HEAD。
            Console.WriteLine(response.StatusCode);
            Assert.True(response.IsSuccessStatusCode);
        }
    }
}


本文转自田园里的蟋蟀博客园博客,原文链接:http://www.cnblogs.com/xishuai/p/designing-rest-api-uri-for-checking-resource-existence.html,如需转载请自行联系原作者

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,大概有三种登录方式:
10010 0
使用SSH远程登录阿里云ECS服务器
远程连接服务器以及配置环境
13979 0
阿里云服务器怎么设置密码?怎么停机?怎么重启服务器?
如果在创建实例时没有设置密码,或者密码丢失,您可以在控制台上重新设置实例的登录密码。本文仅描述如何在 ECS 管理控制台上修改实例登录密码。
20693 0
腾讯云服务器 设置ngxin + fastdfs +tomcat 开机自启动
在tomcat中新建一个可以启动的 .sh 脚本文件 /usr/local/tomcat7/bin/ export JAVA_HOME=/usr/local/java/jdk7 export PATH=$JAVA_HOME/bin/:$PATH export CLASSPATH=.
14117 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
18992 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,云吞铺子总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系统盘、创建快照、配置安全组等操作如何登录ECS云服务器控制台? 1、先登录到阿里云ECS服务器控制台 2、点击顶部的“控制台” 3、通过左侧栏,切换到“云服务器ECS”即可,如下图所示 通过ECS控制台的远程连接来登录到云服务器 阿里云ECS云服务器自带远程连接功能,使用该功能可以登录到云服务器,简单且方便,如下图:点击“远程连接”,第一次连接会自动生成6位数字密码,输入密码即可登录到云服务器上。
33613 0
使用NAT网关轻松为单台云服务器设置多个公网IP
在应用中,有时会遇到用户询问如何使单台云服务器具备多个公网IP的问题。 具体如何操作呢,有了NAT网关这个也不是难题。
35346 0
阿里云服务器安全组设置内网互通的方法
虽然0.0.0.0/0使用非常方便,但是发现很多同学使用它来做内网互通,这是有安全风险的,实例有可能会在经典网络被内网IP访问到。下面介绍一下四种安全的内网互联设置方法。 购买前请先:领取阿里云幸运券,有很多优惠,可到下文中领取。
19219 0
+关注
3656
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
JS零基础入门教程(上册)
立即下载
性能优化方法论
立即下载
手把手学习日志服务SLS,云启实验室实战指南
立即下载