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

RESTful api主要的意义在于它可以让在不同形式的前端所接受到的用户请求能够统一的发送到一个后台并返回不同的前端。RESTful api是由后端SERVER实现并提供给前端来调用的一个接口。前端调用API来向后台发起HTTP请求,后台响应请求并将处理结构反馈给前端。所以说RESTful是典型的基于HTTP的协议。所以下面我们对RESTful api的设计原则与规范进行相应的说明:

https://blog.csdn.net/qq_31805915/article/details/79951929

一、协议

API与用户的通信协议,总是使用HTTPs协议。

二、域名

尽量将API部署在专用域名之下:

例如https://api.jupiter.com

三、版本

将我们API的版本号放入URL中:

例如https://api.jupiter.com/v1/

四、路径

路径又称"终点"(endpoint),表示API的具体网址。

在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样:

https://api.jupiter.com/zoo

https://api.jupiter.com/animals

https://api.jupiter.com/employees

五、HTTP动词

对于资源的具体操作类型,由HTTP动词来表示,常用的HTTP动词有下面五个(括号中对应的是相应的SQL命令):

GET(SELECT):从服务器取出资源(一项或多项)。

POST(CREATE):在服务器新建一个资源。

PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。

PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。

DELETE(DELETE):从服务器删除资源。

下面是一些简单的例子:

GET /zoos:列出所有动物园

POST /zoos:新建一个动物园

GET /zoos/ID:获取某个指定动物园的信息

PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)

PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)

DELETE /zoos/ID:删除某个动物园

GET /zoos/ID/animals:列出某个指定动物园的所有动物

DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

六、过滤信息

如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果,下面是一些常见的参数:

?limit=10:指定返回记录的数量

?offset=10:指定返回记录的开始位置。

?page=2&per_page=100:指定第几页,以及每页的记录数。

?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。

?animal_type_id=1:指定筛选条件

参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

七、状态码

服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词):

200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。

201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。

202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)

204 NO CONTENT - [DELETE]:用户删除数据成功。

400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。

401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。

403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。

404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。

406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。

410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。

500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

详细的状态码列表可见这里

八、错误处理

如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。

例如:

  1.  
    {
  2.  
    error: "Invalid API key"
  3.  
    }

九、返回结果

针对不同操作,服务器向用户返回的结果应该符合以下规范:

GET /collection:返回资源对象的列表(数组)

GET /collection/resource:返回单个资源对象

POST /collection:返回新生成的资源对象

PUT /collection/resource:返回完整的资源对象

PATCH /collection/resource:返回完整的资源对象

DELETE /collection/resource:返回一个空文档

后端api规范说明文档的更多相关文章

  1. Java Servlet API中文说明文档

    Java Servlet API中文说明文档 目 录 1.... Servet资料 1.1      绪言 1.2      谁需要读这份文档 1.3      Java Servlet API的组成 ...

  2. Web API 接口说明文档

    1.采用 Web API Help Page 显示效果 2.swaggerui 创建文档接口 效果图 3.swagger ui 安装配置 nuget 安装 2.设置xml文件 3.配置根路径 预览sw ...

  3. 迅雷 API 接口说明文档 -调用迅雷自动下载

    我们可以利用迅雷提供的开放API接口来自动下载文件.详细的接口说明大家可以看下面的. 先要说明一下的就是 迅雷的API接口是用 .com 来调用的 首先就是脚本了,各种语言写法不同,我这里提供用vbs ...

  4. RESTful API接口文档规范小坑

    希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...

  5. ASP.NET WebApi使用Swagger生成api说明文档

    最近做的项目使用mvc+webapi(非.Net Core),采取前后端分离的方式,后台提供API接口给前端开发人员.这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用 ...

  6. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  7. NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因

    认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参 ...

  8. .NET Core WebApi帮助文档使用Swagger生成Api说明文档

    Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什么选择 ...

  9. 使用swagger生成API说明文档

    使用swagger生成API说明文档本文由个人总结,如需转载使用请标明原著及原文地址没有导出!!!!!不要整天给我留言导出呢,那个是你们百度的时候下面的推荐文章带的关键字,要做导出从swagger取数 ...

随机推荐

  1. Asp.Net Core中DI的知识总结

    在asp.net core中DI的概念是由这几部分组成的: IServiceCollection,保存IServiceDescriptor实例的列表 IServiceProvider,只有一个方法Ge ...

  2. 搭建一个简单的本地的dubbo-demo案例

    一.创建一个Maven工程,然后创建三个module模块 二.dubbo-api(maven模块) 创建一个api类,命名为ApiService.java package com.example.se ...

  3. delphi ehLib 安装包下载及安装方法

    1.下载安装包,这里提供一个百度云盘共享链接,D7-XE8都有:https://pan.baidu.com/s/1DTlxok4RiSmDokuabnGvQw2.添加环境变量,菜单"Tool ...

  4. 2019春招面试高频题(Java版),持续更新(答案来自互联网)

    第一模块--并发与多线程 Java多线程方法: 实现Runnable接口, 继承thread类, 使用线程池 操作系统层面的进程与线程(对JAVA多线程和高并发有了解吗?) 计算机资源=存储资源+计算 ...

  5. 2018-2019 ACM-ICPC Nordic Collegiate Programming Contest (NCPC 2018) - 4.28

    赛后补了几道 赛中我就写了两个... A - Altruistic AmphibiansGym - 101933A 看了眼榜没几个人做.就没看. 最后发现就是一个DP(但是我觉得复杂度有点迷) 题意: ...

  6. 前端js日期时间格式转换

    前端前后端接口处理时经常会遇到需要转换不同时间格式的情况,比如时间戳格式转换成正常日期显示来进行前端展示. 下面是分享一些不同格式的日期转换函数方法. /** * 时间戳转时间 * @param {S ...

  7. P1177 【模板】快速排序(学完归并和堆排之后的二更)

    P1177 [模板]快速排序 不用说,连题目上都标了是一道模板,那今天就来对能用到的许多排序方式进行一个总结: 选择排序 选择排序(Selection sort)是一种简单直观的排序算法.它的工作原理 ...

  8. termux

    使用http服务,链接原服务器要挂vpn. apt edit-sources 如果提示 $ apt edit-sources e: Sub-process editor returned a n er ...

  9. CF1152E Neko and Flashback--欧拉路径

    RemoteJudge 第一次见到欧拉路径的题 注意到\(b\)和\(c\)的构造方法很特殊,即对于一个位置(经过\(p\)作用后)\(i\),若两个数分别为\(b_i\)和\(c_i\),那么在\( ...

  10. python中__init__和__new__的区别

    参考:https://my.oschina.net/liuyuantao/blog/747164 python中__metaclass的详解 参考:https://www.cnblogs.com/ia ...