API设计要点

最新推荐文章于 2024-02-20 11:30:00 发布
最新推荐文章于 2024-02-20 11:30:00 发布
阅读量139 收藏
点赞数
文章标签： json 数据库 运维
原文链接：https://segmentfault.com/a/1190000004503009
版权

序

本文主要简述API设计的要点。整体会偏向HTTP的接口，部分同样适合非HTTP的接口。

API版本管理

多版本兼容(控制维护的版本数，不宜过多)

HTTP GET:
https://haveibeenpwned.com/api/breachedaccount/foo
api-version: 2

spring中直接@RequestMapping(headers="api-version=2")即可以自动分发

  • content-type accept

HTTP GET:
https://haveibeenpwned.com/api/breachedaccount/foo
Accept: application/vnd.haveibeenpwned.v2+json

  • content-type accept(版本单独字段)

HTTP GET:
https://haveibeenpwned.com/api/breachedaccount/foo
Accept: application/vnd.haveibeenpwned+json; version=2.0

如何下架旧版本(对过期版本的处理)

  • 对既有版本的访问进行监控

  • 对要下架的版本随机返回错误

API安全认证(两方认证vs三方认证)

两方认证，只涉及api服务提供方和使用方；

clipboard.png

三方认证，多了个用户，通常是采用OAuth2来进行授权认证。

clipboard.png

下面的这些仅仅涉及两方认证(双方认证的 api 通常的认证方式是使用一组 id 和密钥，用 id 来标记应用，用密钥来对请求做签名)：

  • 开启https(web api的话)

  • Http Basic Authentication(一般内网使用配合https)
    在 Http header 中添加键值对 Authorization: Basic xxx （xxx 是 username:passowrd base64 值）。

  • 黑白名单(内网白，外网黑)

  • JWT (JSON Web Token)(适合移动端)
    JWT认证协议的格式为Header.Payload.Signature。比如xxxxx.yyyyy.zzzzz。签名内容是有Header+Payload+Secret通过HMAC SHA256算法加密而成。

clipboard.png
具体参考Introduction to JSON Web Tokens

API限流措施

HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug 2013 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "API rate limit exceeded. \
See http://developer.github.com/v3/ \
#rate-limiting for details."
}

API的文档化

业界的两个方案，一个是Swagger使用Swagger快速打造REST API文档，一个是最新的spring restdocs

API的接口设计

  • 错误码处理
    建议充分利用http的错误码，然后再细分，不建议自己再重新自定义一套。

    • 请求成功

      • 200 OK : 请求执行成功并返回相应数据，如 GET 成功

      • 201 Created : 对象创建成功并返回相应资源数据，如 POST 成功；创建完成后响应头中应该携带头标 Location ，指向新建资源的地址

      • 202 Accepted : 接受请求，但无法立即完成创建行为，比如其中涉及到一个需要花费若干小时才能完成的任务。返回的实体中应该包含当前状态的信息，以及指向处理状态监视器或状态预测的指针，以便客户端能够获取最新状态。

      • 204 No Content : 请求执行成功，不返回相应资源数据，如 PATCH ， DELETE 成功

    • 重定向
      重定向的新地址都需要在响应头 Location 中返回

      • 301 Moved Permanently : 被请求的资源已永久移动到新位置

      • 302 Found : 请求的资源现在临时从不同的 URI 响应请求

      • 303 See Other : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该使用 GET 方法进行请求

      • 307 Temporary Redirect : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该保持原有的请求方法进行请求

    • 条件请求

      • 304 Not Modified : 资源自从上次请求后没有再次发生变化，主要使用场景在于实现数据缓存

      • 409 Conflict : 请求操作和资源的当前状态存在冲突。主要使用场景在于实现并发控制

      • 412 Precondition Failed : 服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。主要使用场景在于实现并发控制

    • 客户端错误

      • 400 Bad Request : 请求体包含语法错误

      • 401 Unauthorized : 需要验证用户身份，如果服务器就算是身份验证后也不允许客户访问资源，应该响应 403 Forbidden

      • 403 Forbidden : 服务器拒绝执行

      • 404 Not Found : 找不到目标资源

      • 405 Method Not Allowed : 不允许执行目标方法，响应中应该带有 Allow 头，内容为对该资源有效的 HTTP 方法

      • 406 Not Acceptable : 服务器不支持客户端请求的内容格式，但响应里会包含服务端能够给出的格式的数据，并在 Content-Type 中声明格式名称

      • 410 Gone : 被请求的资源已被删除，只有在确定了这种情况是永久性的时候才可以使用，否则建议使用 404 Not Found

      • 413 Payload Too Large : POST 或者 PUT 请求的消息实体过大

      • 415 Unsupported Media Type : 服务器不支持请求中提交的数据的格式

      • 422 Unprocessable Entity : 请求格式正确，但是由于含有语义错误，无法响应

      • 428 Precondition Required : 要求先决条件，如果想要请求能成功必须满足一些预设的条件

    • 服务端错误

      • 500 Internal Server Error : 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。

      • 501 Not Implemented : 服务器不支持当前请求所需要的某个功能。501 与 405 的区别是：405 是表示服务端不允许客户端这么做，501 是表示客户端或许可以这么做，但服务端还没有实现这个功能

      • 502 Bad Gateway : 作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。

      • 503 Service Unavailable : 由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间（内容可以为数字，单位为秒；或者是一个 HTTP 协议指定的时间格式）。如果没有给出这个 Retry-After 信息，那么客户端应当以处理 500 响应的方式处理它。

    • 错误码带描述

503 Service Unavailable
{
"error_human": "The Database is currently unavailable.",
"error_code": "database_unavailable" (使用文字描述比起使用数字code会使开发者更容易懂)
}

  • 分页

GET /employees?left=true&fields=name,joinDate&limit=10&offset=0&sortby=name&order=asc
{
    "data": {
        "total": 150,
        "employees": [
            {
                "name": "tom",
                "joinDate": "2015-10-01"
            },
            {
                "name": "jack",
                "joinDate": "2015-10-02"
            }
        ]
    }
}

或者采用page的方式同时加入links提示

?page=1&pre_page=10
{
    "data": {
        "total": 150,
        "links": [
            {
                "rel": "next",
                "href": "?page=2&per_page=10"
            },
            {
                "rel": "last",
                "href": "?page=11&per_page=10"
            }
        ],
        "employees": [
            {
                "name": "tom",
                "joinDate": "2015-10-01"
            },
            {
                "name": "jack",
                "joinDate": "2015-10-02"
            }
        ]
    }
}

或者

?limit=10: Reduce the number of results returned to the Consumer (for Pagination)
?offset=10: Send sets of information to the Consumer (for Pagination)
?limit=25&offset=50

  • 排序

?sortby=name&order=asc: Sort the results based on the specified attribute (ORDER BY name ASC)

  • 查询字段选择

GET http://api.example.org/user/12?fields=id,name,email (SELECT id, name, email FROM user WHERE user.id = 12)

  • 查询过滤

?q=fluffy+fur(搜索)
?animal_type_id=1: Filter records which match the following condition (WHERE animal_type_id = 1)

  • 其他

    • HATEOAS
      HATEOAS是Hypermedia as the Engine of Application State的缩写形式，中文意思为：超媒体应用状态引擎。它的核心思想是使用超媒体表达应用状态，与hypertext-driven思想是一致的。在此之前，我们大多数的程序业务控制在前台完成。例如：我们会在前台做注册流程，我们在前台判定下一步应该做什么，可以做什么。当使用HATEOAS时，这些状态流程控制都在应用程序的后台完成。我们使用超媒体来表达前台做完某一步骤之后可以做哪些? 这样一来，前台的任务就变得相当简单了，前台需要处理的是理解状态表述，数据收集和结果显示。

    • url组成

      • 网络协议(HTTP, HTTPS)

      • 服务器地址

      • 版本

      • 接口名称（用-代替_）

      • ?参数列表（之后返回接口instagram是用_代替驼峰的）

    • url命名限制

      • 不使用大写字母

      • 使用中线-代替下划线_，比如instagram的一个接口，https://api.instagram.com/v1/users/{user-id}/followed-by?access_token=ACCESS-TOKEN

      • 参数列表应该被encode过

    • 聚合资源必须通过父级资源操作
      示例: Profile是User的聚合资源，User有一个唯一且私有的Profile资源，只能通过User操作Profile。/users/123456/profiles

    • 组合资源要避免资源路径嵌套
      示例: 一个系统里面包含多个 applications，一个 application 又包含多个 users。那获取 user 资源的路径应该是怎样的？

 GET http://~/$version/systems/:systemId/applications/:applicationId/users/:userId

改为

GET http://~/$version/systems/:systemId
GET http://~/$version/applications/:applicationId
GET http://~/$version/users/:userId/

参考

weixin_34289744
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
API接口安全设计方案（已实现）
软件老王
07-16 1万+
1、背景 网络安全方案，主要从数据加密与api接口安全两个方面考虑，数据加密https已经加密了，就不再次加密了；主要从api安全方面考虑。 2、接口安全设计 在代码层面，对接口进行安全设计 一、使用token进行用户身份认证 二、使用sign防止传入参数被篡改 三、用时间戳防止暴力请求 一、使用token进行用户身份认证 用户身份认证的流程图如下： 具体说明如下： 1、 用户登录时，客户端请求接口，传入用户名和密文的密码 2、 后台服务对用户身份进行验证。若验证失败，则返回错误结果；若验证通过，则生成一
「译」API 安全最佳实践，不要等出事后“捶胸顿足”
HelloGitHub 的博客
10-26 1146
原文地址：API Security Best Practices[1]原文作者：Mark Michon译者 & 校正：HelloGitHub-小鱼干 & HelloGit...
12 个设计 API 的安全建议，不要等出事儿了“捶胸顿足”
m0_59598029的博客
01-07 108
虽然本质上 API 就是拿来用的，但即便某个 API 的使用者全是内部人员，它还是可能会出现安全问题。为了解决 API 安全问题，在本文我们收集了一系列 API 的最佳实践，希望你记住这些 Tips 日后在保护 API/Web 服务安全和免受入侵时，会帮助到你。
API 接口怎样设计才安全？
A_991128a的博客
02-20 1193
设计安全的API接口是确保应用程序和数据安全的重要方面之一。
API安全（二）：API安全设计原则
weixin_43923647的博客
06-10 922
很多API安全问题的产生的根源是缺少好的API安全设计，做好API安全设计有利于提升API自身的安全性。这里将讲2条设计原则：5A原则和纵深防御原则。 一、5A原则
API安全接口安全设计
yshir
05-15 323
如何保证外网开放接口的安全性。 使用加签名方式，防止数据篡改 信息加密与密钥管理 搭建OAuth2.0认证授权 使用令牌方式 搭建网关实现黑名单和白名单 一令牌方式搭建搭建API开放平台 方案设计： 1第三方机构申请一个appId,通过appId去获取accessToken,每次请求获取accessToken都要把老的accessToken删掉 2第三方机构请求数据需要加上accessToken参数，每次业务处理中心执行业务前，先去dba持久层查看accessToken是否存在(可以把
API设计标准
软件与艺术
01-07 977
API是两个系统之间交互的协议，在设计时需充分考虑清楚服务请求方和服务提供方的场景。 对外API是系统对API用户提供的服务，需要考虑到API用户的使用特点。本文提出了针对API用户的设计标准，作为参考。 设计要点 API设计时需要考虑以下方面：灵活性、一致性、兼容性 灵活性，API用户使用程序调用接口，因此一个接口应该尽可能满足多种场景，减少限制； 一致性，API用户学习接口有成本，因此不同的接口之间的术语和逻辑尽可能保持一致； 兼容性，API用户的程序修改起来有成本，因此每次接口的更新需要保
RESTful API设计规范
12-21
以下将详细阐述RESTful API设计的关键要点。 首先，REST（Representational State Transfer，表征状态转移）是一种软件架构风格，它强调资源的概念，通过统一资源标识符（URI，通常是URL）来定位资源，使用HTTP方法...
HadoopYARN架构设计要点
02-26
YARN是开源项目Hadoop的一个资源管理系统，最初设计是为了解决Hadoop中MapReduce计算框架中的资源管理问题，但是现在它已经是一个更加通用的资源管理系统，可以把MapReduce计算框架作为一个应用程序运行在YARN系统之...
SparkStandalone架构设计要点分析
02-25
ApacheSpark是一个开源的通用集群计算系统，它提供了High-level编程API，支持Scala、Java和Python三种编程语言。Spark内核使用Scala语言编写，通过基于Scala的函数式编程特性，在不同的计算层面进行抽象，代码设计...
REST API 安全设计指南.pdf
05-12
REST API 安全设计指南。REST的全称是REpresentational State Transfer，它利用传统Web特点，提出 提出一个既适于客户端应用又适于服务端的应用的、统一架构，极大程度上统一及简化了网站架构设计。 目前在三种主流的Web服务实现方案中，REST模式服务相比复杂的SOAP和XML-RPC对比来讲，更加简 洁，越来越多的web服务开始使用REST设计并实现。但其缺少安全特性，《REST API 安全设计指南》就 是一个REST API安全设计的指南，权当抛砖引玉，推荐网站后台设计及网站架构师们阅读。
接口设计需要考虑哪些方面
pscsx的专栏
03-31 2421
接口设计需要考虑的点
接口设计，这36个核心知识点一定要注意！
架构师小秘圈
05-30 572
目录前言设计好接口的 36 个锦囊总结前言作为后端开发，不管是什么语言，Java、Go 还是 C++，其背后的后端思想都是类似的。我们做后端开发工程师，主要工作就是：如何把一个接口设计好。所以，今天就给大家介绍，设计好接口的 36 个锦囊。设计好接口的 36 个锦囊| 接口参数校验入参出参校验是每个程序员必备的基本素养。你设计的接口，必须先校验参数。比如入参是否允许为空，...
设计安全的接口api
it_manman的博客
03-01 368
接口的安全性主要围绕Token、Timestamp和Sign三个机制展开设计，保证接口的数据不会被篡改和重复调用，下面具体来看：Token授权机制：用户使用用户名密码登录后服务器给客户端返回一个Token（通常是UUID），并将Token-UserId以键值对的形式存放在缓存服务器中。服务端接收到请求后进行Token验证，如果Token不存在，说明请求无效。Token是客户端访问服务端的凭证。时间...
一篇文章帮你梳理清楚API设计时需要考虑的几个关键点
渡江客涂鸦板
11-07 2884
微服务架构提倡有许多职责单一的小服务组成，这些服务之间互相交互。然而这就造成了一系列的问题，比如：服务之间如何发现彼此？是否采用统一的协议？如果一个服务无法与其他服务通信会怎样？我会在接下来的内容里讨论部分相关话题
API知识点总结
cuizero
12-19 439
一、获取元素 1.document.getElementById（） 获取id名；获取是个元素；没有获取到的话是Null； 2.getElementsByTagName(） 获取标签名；获取的是该标签名的元素的集合，获取到的是个数组，没有的话是[]； 3.getElementsByClassName(） 获取类名；获取的是该标签class名的元素的集合，获取到的是个数组，没有的话是[]； 4.querySelector( ) 获取的是是改标签元素 5.querySelectorAll( )
RESTful API接口设计标准及规范；
热门推荐
时光偏执的博客
01-12 28万+
RESTful发展背景及简介 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 REST（Representational Stat...
restfulapi设计
最新发布
03-05
下面是RESTful API设计的一些要点： 1. 使用合适的HTTP动词RESTful API使用HTTP动词（GET、、PUT、DELETE等）来表示对资源的不同操作。GET用获取资源，POST用于创建资源，PUT用于更新资源，DELETE用于删除资源。 2...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值