api规范PHP,RESTful API规范(详细版)
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:
但是,实际上URI中的每个字符都会计入资源的唯一身份的识别中。
两个不同的URI映射到两个不同的资源。如果URI不同,那么资源也是如此,反之亦然。因此,REST API必须生成和传递精确的URI,不能容忍任何的客户端尝试不精确的资源定位。
有些API碰到这种情况,可能设计为让客户端重定向到相应没有尾斜杠的URI(也有可能会返回301 – 用来资源重定向)。
正斜杠分隔符”/“必须用来指示层级关系
rul的路径中的正斜杠“/“字符用于指示资源之间的层次关系。
例如:
应该使用连字符”-“来提高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状态码
有很多服务器将返回状态码一直设为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占用率大,等.
api规范PHP,RESTful API规范(详细版)的更多相关文章
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- 【API设计】RESTful API 设计指南
RESTful API URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作. 例如 . REST描述的是在网络中client和server的一种交互形式:REST本身不 ...
- Web API 入门系列 - RESTful API 设计指南
参考:https://developer.github.com/v3/ https://github.com/bolasblack/http-api-guide HTTP 协议 目前使用HTTP1. ...
- RESTful API规范
1. 域名 应该尽量将API部署在专用的域名下. https://api.example.com 如果确定API简单,不会有进一步的括在,可以考虑放在主域名之下. https://example.or ...
- 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 ...
- 用ASP.NET Core 2.1 建立规范的 REST API -- 翻页/排序/过滤等
本文所需的一些预备知识可以看这里: http://www.cnblogs.com/cgzl/p/9010978.html 和 http://www.cnblogs.com/cgzl/p/9019314 ...
- 你真的了解restful api吗?
前言 在以前,一个网站的完成总是“all in one”,页面,数据,渲染全部在服务端完成,这样做的最大的弊端是后期维护,扩展极其痛苦,开发人员必须同时具备前后端知识.于是慢慢的后来兴起了前后端分离的 ...
- 使用ASP.NET Core 3.x 构建 RESTful API - 1.准备工作
以前写过ASP.NET Core 2.x的REST API文章,今年再更新一下到3.0版本. 先决条件 我在B站有一个非常入门的ASP.NET Core 3.0的视频教程,如果您对ASP.NET Co ...
- 一文搞懂RESTful API
RESTful接口实战 原创公众号:bigsai 转载请联系bigsai 文章收藏在回车课堂 前言 在学习RESTful 风格接口之前,即使你不知道它是什么,但你肯定会好奇它能解决什么问题?有什么应用 ...
- Restful API是什么、为什么、怎么使用
Restful API 文章目录 Restful API 1.REST是什么以及它的 6 个限制 REST是什么? REST的6个限制 2. Restful是什么 Restful是什么 RESTful ...
随机推荐
- USB转TTL串口 (CH340 G)
为什么USB要转TTL串口[1]? 单片机串口基本采用TTL电平. 家用电脑很少有串口,但是有USB接口 USB的电平与TTL电平不兼容. 所以需要将USB电平转化为TTL电平. USB是什么? 接口 ...
- EXACT函数
EXACT函数:EXACT函数是一个文本函数,通过这个函数可以将不同的字符串进行对比,通常用于信息核对. EXACT函数的功能:比较两个字符串是否一致,返回不同的结果. EXACT函数的语法结构:EX ...
- Spark详解(06) - SparkSQL
Spark详解(06) - SparkSQL Spark SQL概述 什么是Spark SQL Spark SQL是Spark用于结构化数据(Structured Data)处理的Spark模块. ( ...
- Java学习笔记:2022年1月6日
Java学习笔记:2022年1月6日 摘要:不可变字符串为什么不可变?StringBuffer类与StringBuilder类,字符串操作拾遗,记事本原理,进制转化问题. 目录 Java学习笔记:20 ...
- 本地文件上传 Gitee 和 GitHub
新建仓库 上 GitHub 或者是 gitee 创建仓库 在所在的文件夹打开终端 在本地项目文件夹打开终端, 或者 cd 到本地项目文件夹 配置提交项目的用户名和提交项目的邮箱 git config ...
- 异常概念&异常体系-异常分类
异常概念&异常体系 异常,就是不正常的意思.在生活中:医生说,你的身体某个部分有异常,该部位和正常相比有点不同,该部位的功能将受影响,在程序中的意思就是: 异常:指的是程序在执行过程中,出现的 ...
- 创建型模式 - 单例模式Singleton
单例模式的定义与特点 创建型模式: 单例模式的定义:指一个类只有一个实例,且该类能自行创建这个实例的一种模式. 例如,Windows中只能打开一个任务管理器,这样可以避免因打开多个任务 ...
- bash原样输出字符串中的换行
➜ code $ cat test.sh #!/bin/bash nr="`cat -`"\" echo "$nr" echo $nr echo &q ...
- exgcd & 线性同余方程
前置芝士 裴蜀定理 同余的性质 exgcd exgcd即扩展欧几里得定理,常用来求解\(ax + by = gcd(a,b)\)的可行解问题 推导过程: 考虑我们有: \(ax + by = gc ...
- Grafana 系列文章(十四):Helm 安装Loki
前言 写或者翻译这么多篇 Loki 相关的文章了, 发现还没写怎么安装 现在开始介绍如何使用 Helm 安装 Loki. 前提 有 Helm, 并且添加 Grafana 的官方源: helm repo ...