RESTful API 最佳实践

简介: RESTful API 最佳实践

RESTful API 最佳实践

RESTful 是目前最流行的 API 规范,适用于 Web 接口规范的设计。让接口易读,且含义清晰。本文将介绍如何设计易于理解和使用的 API,并且借助 Docker api 的实践说明。

URL 设计

1.1 动词 + 宾语

它的核心思想就是客户端发出的数据操作指令都是「动词 + 宾语」的结构,比如 GET /articles这个命令,GET是动词,/articles是宾语。

动词通常来说就是五种 HTTP 方法,对应我们业务接口的 CRUD 操作。而宾语就是我们要操作的资源,可以理解成面向资源设计。我们所关注的数据就是资源。

  • GET: 读取资源
  • POST:新建资源
  • PUT:更新资源
  • PATCH:资源部分数据更新
  • 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:删除某个指定动物园的指定动物

1.2 动词的覆盖

有些客户端只能使用GET和POST这两种方法。服务器必须接受 POST 模拟其他三个方法(PUT、PATCH、DELETE)。

这时,客户端发出的 HTTP 请求,要加上 X-HTTP-Method-Override 属性,告诉服务器应该使用哪一个动词,覆盖 POST 方法。

1.3 宾语必须是名词

就是 API 的url ,是 HTTP 动词作用的对象,所以应该是名词。例如 /books 这个 URL 就是正确的,而下面的 URL 不是名词,都是错误的写法。

错误示范:

GET /getAllUsers?name=jl
POST /createUser
POST /deleteUSer

1.4 复数名词

URL 是名词,那么是使用复数还是单数?

没有统一的规定,但是我们通常操作的数据多数是一个集合,比如 GET /books ,所以我们就使用复数。

统一规范,建议都使用复数 URL, 比如 获取 id = 2 的书 GET /books/2 要好于 GET /book/2

1.5 避免出现多级 URL

有时候我们要操作的资源可能是有多个层级,因此很容易写多级 URL,比如获取某个作者某种分类的文章。

GET /authors/2/categories/2 获取作者ID = 2 分类 = 2 的文章

这种 URL 不利于拓展,语义 也不清晰。

更好的方式就是 除了第一级,其他级别都是通过查询字符串表达。

正确方式: GET /authors/12?categories=2

查询已发布的文章

错误 写法: GET /artichels/published

正确写法: GET /artichels?published=true

过滤信息(Filtering)

状态码如果记录数量很多,服务器不可能都将它们返回给用户。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 的含义是相同的。推荐后者,避免出现多级URL。

2.1 状态码必须精确

客户端的请求,服务求都必须响应,包含 HTTP 状态码和数据。

HTTP 状态码就是一个三位数,分成五个类别。

  • 1xx:相关信息
  • 2xx:操作成功
  • 3xx:重定向
  • 4xx:客户端错误
  • 5xx:服务器错误

2.2 2xx 状态码

200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

  • GET: 200 OK
  • POST: 201 Created
  • PUT: 200 OK
  • PATCH: 200 OK
  • DELETE: 204 No Content

2.3 4xx 状态码

4xx状态码表示客户端错误,主要有下面几种。

  • 400 Bad Request:服务器不理解客户端的请求,未做任何处理。
  • 401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。
  • 403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。
  • 404 Not Found:所请求的资源不存在,或不可用。
  • 405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。
  • 410 Gone:所请求的资源已从这个地址转移,不再可用。
  • 415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。
  • 422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。
  • 429 Too Many Requests:客户端的请求次数超过限额。

2.4 5xx 状态码

5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

  • 500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。
  • 503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

服务器响应

3.1 不要返回纯文本

API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的 Content-Type 属性要设为 application/json 。

客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT 属性也要设成 application/json。下面是一个例子。

3.2 发生错误的时候,不要返回 200 状态码

有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。

错误例子:

HTTP/1.1 200 OK
ConteNTP-Type: application/json
{
"status": "fail",
"msg": "错误"
}

上面代码中,解析数据体以后,才能得知操作失败。

这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。

正确方式:

HTTP/1.1 400 Bad Request
ConteNTP-Type: application/json
{
"status": "fail",
"msg": "错误"
}

docker RESTful 规范解析

接下来我们分析 docker api 对于 restful 的使用,助于我们在实际工作中合理设计。

docker 文档 url :https://docs.docker.com/engine/api/v1.19/

4.1 GET 获取容器列表

GET /v1.19/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1

通过 all=1&before=8dfafdbc3a40&size=1 过滤容器数据

4.2 GET 获取指定ID或者名字容器

GET /containers/(id or name)/json

GET /v1.19/containers/4fa6e0f0c678/json HTTP/1.1

4.3 GET 获取某个容器的进程

GET /v1.19/containers/4fa6e0f0c678/top HTTP/1.1

假如想过滤进程等可以通过查询字符串实现

GET /v1.19/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1

返回的数据

HTTP/1.1 200 OK
Content-Type: application/json
{
  "Titles" : [
    "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
  ]
  "Processes" : [
    [
      "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
    ],
    [
      "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
    ]
  ],
}

4.4 POST 创建容器

POST /containers/create

POST /v1.19/containers/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345
{
      "Hostname": "",
      "Domainname": "",
      "User": "",
      "AttachStdin": false,
      "AttachStdout": true,
      "AttachStderr": true,
      "Tty": false,
      "OpenStdin": false,
      "StdinOnce": false,
      "Env": [
              "FOO=bar",
              "BAZ=quux"
      ],
      "Cmd": [
              "date"
      ],
      "Entrypoint": null,
      "Image": "ubuntu",
      "Labels": {
              "com.example.vendor": "Acme",
              "com.example.license": "GPL",
              "com.example.version": "1.0"
      },
      "Volumes": {
        "/volumes/data": {}
      }
  }

4.5 DELETE 删除容器

根据容器 id 删除一个容器,v是请求是否删除 容器 volumes

DELETE /v1.19/containers/16253994b7c4?v=1 HTTP/1.1

Query parameters:

  • v – 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false.
  • force - 1/True/true or 0/False/false, Kill then remove the container. Default false.
  • link - 1/True/true or 0/False/false, Remove the specified link associated to the container. Default false.


相关文章
|
1月前
|
XML JSON API
识别这些API接口定义(http,https,api,RPC,webservice,Restful api ,OpenAPI)
本内容介绍了API相关的术语分类,包括传输协议(HTTP/HTTPS)、接口风格(RESTful、WebService、RPC)及开放程度(API、OpenAPI),帮助理解各类API的特点与应用场景。
|
2月前
|
监控 安全 API
电商API安全最佳实践:保护用户数据免受攻击
在电商领域,API是连接用户、商家和支付系统的核心枢纽,但也常成为黑客攻击目标。本文系统介绍电商API安全的最佳实践,涵盖HTTPS加密、强认证授权、输入验证、速率限制、日志监控、安全审计及数据加密等关键措施,帮助您有效防范数据泄露与攻击风险,保障业务安全稳定运行。
90 0
|
3月前
|
缓存 安全 API
RESTful与GraphQL:电商API接口设计的技术细节与适用场景
本文对比了RESTful与GraphQL这两种主流电商API接口设计方案。RESTful通过资源与HTTP方法定义操作,简单直观但可能引发过度或欠获取数据问题;GraphQL允许客户端精确指定所需字段,提高灵活性和传输效率,但面临深度查询攻击等安全挑战。从性能、灵活性、安全性及适用场景多维度分析,RESTful适合资源导向场景,GraphQL则适用于复杂数据需求。实际开发中需根据业务特点选择合适方案,或结合两者优势,以优化用户体验与系统性能。
|
3月前
|
JSON 编解码 API
Go语言网络编程:使用 net/http 构建 RESTful API
本章介绍如何使用 Go 语言的 `net/http` 标准库构建 RESTful API。内容涵盖 RESTful API 的基本概念及规范,包括 GET、POST、PUT 和 DELETE 方法的实现。通过定义用户数据结构和模拟数据库,逐步实现获取用户列表、创建用户、更新用户、删除用户的 HTTP 路由处理函数。同时提供辅助函数用于路径参数解析,并展示如何设置路由器启动服务。最后通过 curl 或 Postman 测试接口功能。章节总结了路由分发、JSON 编解码、方法区分、并发安全管理和路径参数解析等关键点,为更复杂需求推荐第三方框架如 Gin、Echo 和 Chi。
|
3月前
|
存储 监控 安全
电商API安全指南:保护数据与防止欺诈的最佳实践
在电商领域,API安全至关重要。本文从基础到实践,全面解析电商API安全策略:通过强认证、数据加密、输入验证及访问控制保护敏感数据;借助速率限制、欺诈检测与行为分析防范恶意行为。同时,强调将安全融入开发生命周期,并提供应急计划。遵循最佳实践,可有效降低风险,增强用户信任,助力业务稳健发展。
104 4
|
2月前
|
缓存 边缘计算 前端开发
从业务需求到技术栈:电商API选型RESTful还是GraphQL?这5个维度帮你决策
在数字经济时代,电商平台的竞争已延伸至用户体验与系统效能。作为连接前后端及各类服务的核心,API接口的架构设计至关重要。本文对比RESTful与GraphQL两大主流方案,从电商场景出发,分析两者的技术特性、适用场景与选型逻辑,帮助开发者根据业务需求做出最优选择。
|
5月前
|
人工智能 运维 关系型数据库
云服务API与MCP深度集成,RDS MCP最佳实践
近日,阿里云数据库RDS发布开源RDS MCP Server,将复杂的技术操作转化为自然语言交互,实现"对话即运维"的流畅体验。通过将RDS OpenAPI能力封装为MCP协议工具,用户只需像聊天一样描述需求,即可完成数据库实例创建、性能调优、故障排查等专业操作。本文介绍了RDS MCP(Model Context Protocol)的最佳实践及其应用,0代码,两步即可轻松完成RDS实例选型与创建,快来体验!
云服务API与MCP深度集成,RDS MCP最佳实践
|
5月前
|
JSON 测试技术 API
书写API文档的最佳实践📚
API文档对开发者体验和API成功至关重要。本文探讨了编写清晰、全面且友好的API文档的最佳实践,包括定义API目的、结构化文档、提供代码示例、处理错误、版本控制及测试验证等关键步骤。通过实际案例(如WeatherAPI),展示了如何优化文档内容,帮助开发者快速上手并高效使用API。同时强调交互式功能、国际化支持和用户反馈的重要性,以提升文档的可用性和全球可达性。高质量文档不仅能推动API采用率,还能培养强大的开发者社区,为API的长期成功奠定基础。
|
6月前
|
XML JSON API
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中,RESTful API和Web服务均用于实现系统间通信,但各有特点。RESTful API遵循REST原则,主要使用HTTP/HTTPS协议,数据格式多为JSON或XML,适用于无状态通信;而Web服务包括SOAP和REST,常用于基于网络的API,采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案,构建高效、可扩展的应用程序。
|
6月前
|
机器学习/深度学习 设计模式 API
Python 高级编程与实战:构建 RESTful API
本文深入探讨了使用 Python 构建 RESTful API 的方法,涵盖 Flask、Django REST Framework 和 FastAPI 三个主流框架。通过实战项目示例,详细讲解了如何处理 GET、POST 请求,并返回相应数据。学习这些技术将帮助你掌握构建高效、可靠的 Web API。