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,如需转载请自行联系原作者
相关文章
|
1天前
|
SQL 分布式计算 DataWorks
DataWorks产品使用合集之使用API调用ODPS SQL时,出现资源被定时任务抢占,该怎么办?
摘要:DataWorks作为一站式的数据开发与治理平台,提供了从数据采集、清洗、开发、调度、服务化、质量监控到安全管理的全套解决方案,帮助企业构建高效、规范、安全的大数据处理体系。以下是对DataWorks产品使用合集的概述,涵盖数据处理的各个环节。
|
1天前
|
API 开发者 网络架构
深入理解RESTful API设计原则与实践
本文将深度剖析RESTful API设计的核心原则,通过实例分析展示如何将这些原则应用于实际开发中。文章将详细探讨资源定位、统一的接口、自描述消息及无状态通信等关键概念,并结合实际案例,指导读者如何构建高效、易于维护的后端服务。
8 1
|
4天前
|
消息中间件 API 数据库
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
|
5天前
|
安全 前端开发 API
深入理解RESTful API设计原则与实践
【7月更文挑战第14天】在数字化时代的浪潮中,后端开发扮演着至关重要的角色,而RESTful API作为现代Web服务通信的基石,其设计质量直接影响到应用的性能与可维护性。本文将通过剖析RESTful API的核心设计原则,结合实际案例,探讨如何构建高效、易于理解和扩展的API。我们将从资源定位、请求方法、状态码使用等方面入手,揭示良好API设计的秘诀,并分享一些最佳实践和常见陷阱,旨在指导开发者打造更加健壮和友好的后端服务接口。
|
5天前
|
搜索推荐 API UED
资源部署及场景API调用体验过程的引导与操作流畅性
资源部署及场景API调用体验过程的引导与操作流畅性
|
7天前
|
XML 缓存 API
深入理解RESTful API设计原则与最佳实践
【7月更文挑战第12天】本文将探索RESTful API设计的核心原则和实用的最佳实践。我们将从REST的基本概念入手,逐步深入到API设计的高级话题,如版本控制、状态码的正确使用以及如何提高API的安全性。此外,我们还将探讨一些常见的设计挑战和解决方案,以帮助开发者构建更加健壮、可维护和用户友好的后端服务。
|
10天前
|
Java API 数据库
使用Spring Boot构建RESTful API
使用Spring Boot构建RESTful API
|
JSON API PHP
CI中如何保护RESTful API
步骤5 保护RESTful API   为了保护RESTful API,可以在application/config/rest.php中设置安全保护级别,如下所示: $config['rest_auth'] = 'basic';    其中保护级别有如下设置:   None:任何人都...
913 0
|
14天前
|
NoSQL 安全 API
如何有效提升 API 接口的安全性?
**API安全关键在于验证和防刷。通过排序参数、生成签名和MD5加密确保请求合法性。使用Redis限制请求频率,防止接口被恶意刷取。验证和防刷策略结合,保护API免受攻击和滥用。**
34 0
|
1天前
|
存储 JSON DataWorks
DataWorks产品使用合集之如何通过数据集成将API接口产生的数据集成到DataWorks?
摘要:DataWorks作为一站式的数据开发与治理平台,提供了从数据采集、清洗、开发、调度、服务化、质量监控到安全管理的全套解决方案,帮助企业构建高效、规范、安全的大数据处理体系。以下是对DataWorks产品使用合集的概述,涵盖数据处理的各个环节。