美文网首页
Rest接口设计之个人理解

Rest接口设计之个人理解

作者: wallikeny | 来源:发表于2017-07-16 11:36 被阅读0次

前言

关于Rest是什么,本文不做任何介绍。这里记录的是:在多年的工作经验中,从书上学到的、代码中看到的接口规范的个人理解与总结。有不正确的地方,欢迎大家指正。
在当前的项目开发中,不同模块之间通常采用API来访问数据,如何约束和管理开发人员交付的接口风格保持一致,开发人员之间彼此能够快速理解、减少不必要的沟通呢?我相信大部分团队在项目开发之初都会针对团队现状制定一些基础接口规范,这样在一定程度上可以明确职责、加快项目进度。当然我也遇到过一些反例,相互之间扯皮的时间都够完成大部分需求开发了。言归正传,既然说到了接口规范了,我就以当前流行的Rest约束作为模板,谈谈我的理解。

REST规范

关于REST API接口,我的总结是:
REST API接口 = 资源地址(URI) + 请求方法(HTTP VERB)
大家可能会说,你是不是少了请求参数?没有,之所以不提参数,因为它不直接影响接口的设计与规范。
一个标准、规范、友好的API接口,应该做到资源地址与请求方法隔离,互不影响。如何理解这名话,请继续往下看。

资源地址(URI)

  1. 为什么是URI,而不是URL?
    在REST原则中,最重要的是定义资源,资源定义好了,其对应的标识符也就有了,那接口的目的就是通过资源的标识符去访问这些资源。因此,这里需要的是资源标识符(URI),而不是资源定位符(URL)。
  2. 资源地址由名词构成
    明确了上述概念,就不难理解为什么资源地址由名词构成了。比较好的示例大家可以参考豆瓣APIGitHub API,可以说是我见过的最标准的API。说白了,接口地址就是资源标识符,因此,它理应由名词组成,不应夹杂着动词出现。大家在实际项目中肯定见过这样的反例:http://xxx.com/abc/def/getUserList或者http://xxx.com/abc/def/createXXX。其实,这就是典型的资源地址与请求方法耦合的例子,开发者可能会说,这样写可以很明确的告诉使用者接口的目的或效果。但实际上呢?这属于多此一举,而且严重违反了REST的设计理念。因为,HTTP协议中已经定义好了资源的增、删、改、查方法。
  3. 资源由复数表示
    定义资源时,通常是对某个对象或服务的抽象,而接口实际上是对抽象后的对象或服务的集合的操作,因此,强烈建议在定义资源地址时使用复数,如http://xxx.com/api/v1/users,表示对用户资源的基本操作。

请求方法

REST原则(或约束)其实是对HTTP协议的补充,本质上也是HTTP请求。HTTP协议已经定义好了常用的增、删、改、查方法,分别对应HTTP请求的POST、DELETE、PUT和GET方法。设计出上一小节那样反例的同学要么是不清楚HTTP协议、要么就是不理解REST原则。因此,遵守最基本的HTTP协议方法就可以让你在无形中成为了REST约束的实践达人。看,就是这么简单。

最佳示例

方法 示例 说明
GET /users 返回用户列表,后面可添加分页信息,如?limit=10&offset=0
GET /users/c12dl3 返回ID为c12dl3的用户详情
POST /users 创建新用户
PUT /users/c12dl3 修改ID为c12dl3的用户信息
DELETE /users/c12dl3 删除ID为c12dl3的用户

写在最后

最核心的两点已经介绍完了,其实关于REST原则还有很多内容,但都没有以上内容可以让人更直观的理解,而且有些特性在实践中很难被真正落实,所以不提也罢。

相关文章

  • Rest接口设计之个人理解

    前言 关于Rest是什么,本文不做任何介绍。这里记录的是:在多年的工作经验中,从书上学到的、代码中看到的接口规范的...

  • 关于REST(笔记)

    我的理解,REST是一种设计风格,用 RESTful实现接口,设计清晰,目的明确,且有利于前后端分离。你好,我好,...

  • 理解并设计rest/restful风格接口

    网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备.....

  • 理解 REST 接口规范

    REST 全称 Representational State Transfer(表现层状态转换),是 Roy Th...

  • 使用 Protobuf 设计 REST API

    概述 一个设计的好的 REST API 接口,需要一个严格的接口定义。本文试图使用 Protobuf 作为接口设计...

  • Django REST framework简介与基于User模型

    本文纯属个人理解仅作参考 Django REST framework 框架是基于Django框架的用户实现接口的工...

  • REST风格接口设计

    REST服务是一种ROA(面向资源)的应用,主要特点就是把信息存在于HTTP协议方法中(GET,PUT),作用域存...

  • 0226 rest接口设计

    image.png 背景 为了更方便的书写和阐述问题,文章中按照第一人称的角度书写。作为一个以java为主要开发语...

  • 小程序全栈学习-REST

    RESTFULAPI是采用REST理论设计的接口,这是比较难的概念,暂且将自己REST的相关知识总结记录下...

  • REST接口设计规范

    REST接口设计规范 URI格式规范 URI(Uniform Resource Identifiers) 统一资源...

网友评论

      本文标题:Rest接口设计之个人理解

      本文链接:https://www.haomeiwen.com/subject/zrtgettx.html