简介

 一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

  rest是一种软件架构风格,如果你们的接口是rest接口,那么就可被认为你们的的接口是restful的,英文名词和形容词的区别。

    rest接口是围绕“资源”展开的,利用HTTP的协议,其实rest本也可以和HTTP无关,但是现在大家普遍的使用rest都是依托于HTTP协议。HTTP 的url即资源。

   RFC 3986定义了通用的URI语法:

URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]

  • scheme: 指底层用的协议,如http、https、ftp
  • host: 服务器的IP地址或者域名
  • port: 端口,http中默认80
  • path: 访问资源的路径,就是咱们各种web 框架中定义的route路由
  • query: 为发送给服务器的参数
  • fragment: 锚点,定位到页面的资源,锚点为资源id

RESTful API设计

资源路径

对于rest资源的定义,即URL的定义,是最重要的;想要设计出优雅的、易读的rest 接口,其实还是听不容易的。

URL中不能有动词

在Restful架构中,每个网址代表的是一种资源,所以网址中不能有动词,只能有名词,动词由HTTP的 get、post、put、delete 四种方法来表示。

URL结尾不应该包含斜杠“/”

这是作为URL路径中处理中最重要的规则之一,正斜杠(/)不会增加语义值,且可能导致混淆。REST API不允许一个尾部的斜杠,不应该将它们包含在提供给客户端的链接的结尾处。
许多Web组件和框架将平等对待以下两个URI:
http://api.canvas.com/shapes/
http://api.canvas.com/shapes

但是,实际上URI中的每个字符都会计入资源的唯一身份的识别中。

两个不同的URI映射到两个不同的资源。如果URI不同,那么资源也是如此,反之亦然。因此,REST API必须生成和传递精确的URI,不能容忍任何的客户端尝试不精确的资源定位。

有些API碰到这种情况,可能设计为让客户端重定向到相应没有尾斜杠的URI(也有可能会返回301 - 用来资源重定向)。

正斜杠分隔符”/“必须用来指示层级关系

rul的路径中的正斜杠“/“字符用于指示资源之间的层次关系。
例如:
http://api.user.com/schools/grades/classes/boys - 学校中所有的男生

http://api.college.com/students/3248234/courses - 检索id为3248234的学生学习的所有课程的清单。

应该使用连字符”-“来提高URL的可读性,而不是使用下划线”_”

为了使URL容易让人们理解,请使用连字符”-“字符来提高长路径中名称的可读性。
一些文本查看器为了区分强调URI,常常会在URI下加上下划线。这样下划线”_”字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。
为避免这种混淆,请使用连字符”-“而不是下划线

URL路径中首选小写字母

RFC 3986将URI定义为区分大小写,但scheme 和 host components除外。

URL路径名词均为复数

为了保证url格式的一致性,建议使用复数形式。

RESTful API对资源的操作

对于rest api资源的操作,由HTTP动词表示

CURD操作

  • GET: 获取资源
  • POST: 新建资源
  • PUT:在服务器更新资源(向客户端提供改变后的所有资源)
  • PATCH: 在服务器更新资源(向客户端提供改变的属性)
  • DELETE:删除资源

PATCH一般不用,用PUT

资源过滤

在获取资源的时候,有可能需要获取某些“过滤”后的资源,例如指定前10行数据

http://api.user.com/schools/grades/classes/boys?page=1&page-size=10

返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为200,然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。由于rest api是直接使用的HTTP协议,所以它的状态码也要尽量使用HTTP协议的状态码。

  • 200 OK 服务器返回用户请求的数据,该操作是幂等的
  • 201 CREATED 新建或者修改数据成功
  • 204 NOT CONTENT 删除数据成功
  • 400 BAD REQUEST 用户发出的请求有问题,该操作是幂等的
  • 401 Unauthoried 表示用户没有认证,无法进行操作
  • 403 Forbidden 用户访问是被禁止的
  • 422 Unprocesable Entity 当创建一个对象时,发生一个验证错误
  • 500 INTERNAL SERVER ERROR 服务器内部错误,用户将无法判断发出的请求是否成功
  • 503 Service Unavailable 服务不可用状态,多半是因为服务器问题,例如CPU占用率大,等等

返回结果

    • GET /collections 返回资源列表
    • GET /collections/:id 返回单独的资源
    • POST /collections 返回新生成的资源对象
    • PUT /collections/:id 返回完整的资源对象
    • PATCH /collections/:id 返回被修改的属性
    • DELETE /collections/:id 返回一个空文档

优秀资源博主:

RESTful介绍和使用教程

优秀资源博主:

RESTful 详解

初识 RESTful API规范的更多相关文章

  1. day71:drf:API接口&Restful API规范&Django Rest Framework&drf中的序列化和反序列化功能

    目录 1.web应用模式 2.API接口 3.Restful API规范 4.序列化 5.Django Rest Framework 1.drf的简单介绍 2.drf的特点 3.如何安装drf 4.d ...

  2. RESTful API规范

    1. 域名 应该尽量将API部署在专用的域名下. https://api.example.com 如果确定API简单,不会有进一步的括在,可以考虑放在主域名之下. https://example.or ...

  3. restful API 规范(转)

    1. URI URI 表示资源,资源一般对应服务器端领域模型中的实体类. URI规范 不用大写: 用中杠-不用下杠_: 参数列表要encode: URI中的名词表示资源集合,使用复数形式. 资源集合 ...

  4. RESTful API 规范(一)

    一,简介 DRF 即Django rest framework 二,rest 规范 1 协议 API 与用户通信,总是使用https协议 2 域名 1) 应尽量将API 部署在域名下(这种情况会存在跨 ...

  5. 初识restful api接口

    一.restful api接口举例 实现功能 传统方式 restful方式 url HTTP方法 url HTTP方法 查询 /user/query?name=knyel GET /user?name ...

  6. restful api 规范

  7. 后端api规范说明文档

    我们此次后端api的实现主要是按照RESTful api规范来设计的,就是符合REST架构下设计api的规范.简单的来说REST结构就是:利用URL定位资源,用HTTP动词(GET,POST,PUT, ...

  8. 理解Restful api的意义

    RESTful API 只是API的设计规范或者是一套设计理论. 单就URL和Method这两个点,你可以这样理解: URL 是用来唯一标示一个互联网资源的,而 Method 是用来标识当前请求对该资 ...

  9. Restful Api CRUD 标准示例 (Swagger2+validator)

    为什么要写这篇贴? 要写一个最简单的CRUD 符合 Restful Api    规范的  一个Controller, 想百度搜索一下 直接复制拷贝 简单修改一下 方法内代码. 然而, 搜索结果让我无 ...

随机推荐

  1. 实操《kubernetes网络权威指南》之tun设备

    跟着网上作一次,OK的. tun.c #include <net/if.h> #include <sys/ioctl.h> #include <sys/stat.h> ...

  2. MVC(基础一)

    MVC学习之前必须掌握的c#基础知识 一.类自动属性 public class Person { //自动属性 public string Name { get; set; } private int ...

  3. docker /var/lib/docker/aufs/mnt 目录满了怎么清理

    1.创建脚本文件 vi cleandocker.sh 内容如下: #!/bin/sh echo "==================== start clean docker contai ...

  4. Salesforce 开发整理(一)测试类最佳实践

    在Sales force开发中完善测试类是开发者必经的一个环节,代码的部署需要保证至少75%的覆盖率,那么该如何写好测试类呢. 测试类定义格式如下: @isTest private class MyT ...

  5. HTML连载49-清除浮动的第三种方式(内外墙法)

    一.清除浮动的第三种方式 1.隔墙法有两种​如下:外墙法和内墙法​.​ 2.外墙法 (1)在两个盒子中间添加一个额外的块级元素 (2)给这个额外添加的块级元素设置:clear:both;属性 注意点: ...

  6. IT兄弟连 Java语法教程 数组 什么是数组

    数组是编程语言中最常见的一种数据结构,可用于存储多个数据,每个数组元素存放一个数据,通常可通过数组元素的索引来访问数组元素,包括为数组元素赋值和取出数组元素的值.Java语言的数组则具有其特有的特征, ...

  7. pytest框架之mark标签

    对测试用例打标签,在运行测试用例的时候,可根据标签名来过滤要运行的用例. 一.注册标签名 1.创建pytest.ini文件,在文件中按如下方式添加标签名: [pytest] markers = smo ...

  8. SpringBoot开发案例之mail中文附件名字乱码

    最近在开发一个邮件发送多附件的微服务,使用的是org.springframework.mail.javamail.JavaMailSender;包下面的JavaMailSender 但是发送出来的附件 ...

  9. python爬取昵称并保存为csv

    代码: import sys import io import re sys.stdout=io.TextIOWrapper(sys.stdout.buffer,encoding='gb18030') ...

  10. Redis系列---redis简介01

    一. 本章我们将用简短的几句话来帮助你快速的了解什么是redis,初学者不必深究 1 Redis简介 Remote Dictionary Server(Redis)是一个开源的使用ANSI C语言编写 ...