RESTful API

最新推荐文章于 2022-04-08 21:35:54 发布
最新推荐文章于 2022-04-08 21:35:54 发布
阅读量380 收藏 1
点赞数 1
文章标签： 设计
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/stSahana/article/details/52217516
版权

RESTful API 设计

​ REST即Representational State Transfer，如果一个架构符合REST原则，就称它为RESTful架构。

​ REST将网站看作是是一个软件，每一次服务端请求都是一个请求资源的过程，资源可以是txt、html、png、avi等,REST定义了一套用于服务器和客户端交互的一套规则。

​ 写作过程中参考了1/2两篇博客，下面谈谈我对RESTful API 设计的理解。

协议

能够使用https的地方一定要使用https协议，https协议有更好的安全性。

域名

应该尽量将API部署在专用域名之下。github即采用这种方式https://api.github.com/

https://api.example.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.org/api/

版本号

  1. 将版本号加入URL

    https://api.example.com/v1/

  2. 将版本号加入HTTP头信息

    Accept: vnd.example-com.foo+json; version=1.0

路径

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

要操作那个表，就应该在URL中指明，如：

https://api.example.com/v1/zoos

HTTP动作

  • GET 用来获取资源，

    • 用来获取zoos的全部信息
    GET https://api.example.com/v1/zoos
    • 获取某个指定动物园的信息
    GET https://api.example.com/v1/zoos/ID

    or

    GET https://api.example.com/v1/zoos?zoo_id=ID
    • 列出某个指定动物园的所有动物
    GET https://api.example.com/v1/zoos/ID/animals

  • POST 用来新建资源，

    • 新建一个动物园
    POST https://api.example.com/v1/zoos

  • PUT：在服务器更新资源（客户端提供改变后的完整资源）。

    • 更新某个指定动物园的信息（提供该动物园的全部信息）
    PUT /zoos/ID

  • PATCH：在服务器更新资源（客户端提供改变的属性）。

    • 更新某个指定动物园的信息（提供该动物园的部分信息）
    PATCH /zoos/ID

  • DELETE 用来删除资源。

    • 删除某个动物园
    DELETE /ZOOS/ID
    • 删除某个指定动物园的指定动物
    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作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

返回结果

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

  • GET /collection：返回资源对象的列表（数组）
  • GET /collection/resource：返回单个资源对象
  • POST /collection：返回新生成的资源对象
  • PUT /collection/resource：返回完整的资源对象
  • PATCH /collection/resource：返回完整的资源对象
  • DELETE /collection/resource：返回一个空文档

返回格式应统一，如：

{
  "status":{
    "status-code"：xxx,
    "message":xxx,//详细的状态信息，如“success”
  },
  "data":{
    //return data here
  }
}

Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上面代码表示，服务器给出了提示信息，以及文档的网址。

其他

（1）API的身份认证应该使用OAuth 2.0框架。

（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。

stSahana
关注
apist, 在html解析中，包提供了诸如访问外部站点的api.zip
10-10
apist, 在html解析中，包提供了诸如访问外部站点的api SleepingOwl Apist SleepingOwl Apist是一个小型库，允许你基于html解析使用api类似的方式访问任何站点。概述这里软件包允许你编写如下方法：class WikiApi e
Python Flask高级编程之RESTFul API前后端分离精讲第七章节
03-19
Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API前后端分离精讲第六章节Python Flask高级编程之RESTFul API...
快手ksjsb普通版cookies提取每日低保
一行真人
03-23 8731
右手就行的快手普通版cookies提取 参考: https://blog.csdn.net/qq_44633541/article/details/123513724 都能看懂的快手极速版cookies提取 CK里的api_st跟快手极速版的通用，但是需要额外一个did(设备号)，同一台设备捉包的话可以把did复制一遍粘贴到每个账号的api_st后面，建议用不同设备捉包！ 青龙把任意包里的kuaishou.api_st=xxxxxxxxxxxx;和did=yyyyyyyyyyy;这两段连在一起放到变量ksC
JavaScript数组的api
qq_44191929的博客
09-06 96
目录 数组的api 1、栈、队列（改变原数组） 1.1 栈（先进后出，后进先出） 1.2 对列（先进先出，后进后出） 2、排序 3、截取 4、索引 5、 迭代 数组的api 1、栈、队列（改变原数组） 1.1 栈（先进后出，后进先出） pop() 将数组的最后一项删除，返回删除的项 push() 可以接受任意数据类型，将参数逐个添加到数组末尾，返回数组的长度 var arr = [1,2,3,4,5,6] console.log('pop删...
Github “message“:“Requires authentication“
weixin_43654123的博客
04-08 1294
GitHub文档. GitHub账户登录遇到的问题 {“message”:“Requires authentication”,“documentation_url”:“https://docs.github.com/rest/reference/users#get-the-authenticated-user”} Use the access token to access the API The access token allows you to make requests to the API o
RESTful API 设计指南
honghailiang的专栏
02-18 518
大师的文章转来学习 http://www.ruanyifeng.com/blog/2014/05/restful_api.html 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备......）。 因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"API First"的设计思想
SpringBoot+Mybatis+CXF框架，实现Restful api与 WebService api接口的大实验
最新发布
04-07
SpringBoot+Mybatis+CXF框架，实现Restful api与 WebService api接口的大实验 本实验的主要目标是使用SpringBoot、Mybatis和CXF框架来实现Restful API和WebService API接口的大实验。下面是实验的详细介绍： 标题...
RESTfulAPI:.net 5构建RESTful API，杨旭学习编码和笔记
03-07
在.NET 5中构建RESTful API是现代Web服务开发中的常见任务，这主要得益于REST（Representational State Transfer）架构风格的广泛采纳。RESTful API设计原则强调资源的表述和状态转移，通过HTTP协议来实现客户端与...
c c++实现http服务 c c++开发restful api服务
02-11
本文将深入探讨如何使用C和C++来实现HTTP服务，并开发RESTful API服务器。 首先，HTTP（超文本传输协议）是互联网上应用最为广泛的一种网络协议，用于从万维网服务器传输超文本到本地浏览器。它是一个基于请求与...
Github Desktop出现Authentication failed错误的解决方法
hhhhhjkk的博客
04-26 1万+
    在上传Repository到github中出现“Authentication failed. You may not have permission to access the repository. Open options and verify that you're signed in with an account that has permission to access thi...
Kotlin新手入坑：协程基本使用以及API...|..ST
蓝渊智海的博客
12-11 447
Kotlin协程协程基本概念和使用协程使用更多作用域构建器   该系列文章仅作为学习记录，如有错误欢迎各位大佬指正 (* ^ ▽ ^ *)   如果与我一样初学，可以评论自己困惑，互相探讨，同时我也会将经典的问题更新到文章中，方便后来者学习。 协程基本概念和使用   协程，和线程类似，可以理解成一种轻量级的线程，协程可以仅在编程语言的层面就能实现不同协程之间的切换，这样就提升了并发编程的运行效率。线程是重量级的，需要依靠操作系统的调度才能实现不同线程之间的切换。 协程运行我们在单个线程模式下模拟多线程
关于GitHub客户端 authentication failed的解决办法
李昊轩的博客
02-01 3978
网上的各种方法都试过了， 包括去控制面板删除钥匙串， git bash删除登陆缓存，repo远程连接 https ssh 互相切换，包括重新登录， 还是没有解决。 偶然尝试将repo的url中加入用户名和密码， https://用户名:密码@github.com/bestksl/xxx.git 问题解决！ ...
Java 调用Restful API接口的几种方式--HTTPS
热门推荐
三丰的专栏
06-20 5万+
摘要：最近有一个需求，为客户提供一些Restful API 接口，QA使用postman进行测试，但是postman的测试接口与java调用的相似但并不相同，于是想自己写一个程序去测试Restful API接口，由于使用的是HTTPS，所以还要考虑到对于HTTPS的处理。由于我也是首次使用Java调用restful接口，所以还要研究一番，自然也是查阅了一些资料。 分析：这个问题与模块之间的调用不
Github Authentication failed（身份验证失败）解决方法 | GitHub Desktop如何退出
我是菜鸡
02-12 3万+
　　昨晚心血来潮改了个git的用户名，改完之后今早晨发现桌面客户端就出问题了。提示以下问题。 Authentication failed. You may not have permission to access the repository or the repository may have been archived. Open options and verify that yo...
REST和RESTful API
answer3lin的博客
01-14 1596
定义 REST即表述性状态传递（英文：Representational State Transfer，简称REST）是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格(software architecture style)。它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。 REST密切相关的两个名词：资源和状态。可以说，资源是RE...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值