ICode9

精准搜索请尝试: 精确搜索
首页 > 其他分享> 文章详细

REST API概述与设计规范

2022-09-17 00:04:39  阅读:7  来源: 互联网

标签:HTTP URI REST API 设计规范 资源 客户端


一、REST API

REST、RESTful、REST API

API: 是应用程序编程接口,是预先定义好的函数,可以供应用程序或开发人员访问调用
REST(Representational State Transfer,表述化状态转移):指的是一组架构约束条件和原则。
RESTful:满足REST约束条件和原则的设计规范或者架构风格
REST API:是北向接口的主流设计方式,遵循RESTful设计的API

为什么需要RESTful

RESTful并不是专门为SDN提出的,而是专门针对Web应用中HTTP使用中出现的一些问题提出的,由于HTTP协议的使用很不规范、随意、混乱
URL的设计缺乏规范性
HTTP的动词使用不当
HTTP的返回状态码使用不规范等
Restful正是针对HTTP中上述问题而提出的

image
image

REST中的几个重要概念

image
资源(resource)

比如在普通的博客应用中,资源可能是包括了用户、博文或者评论等
在SDN中,资源可能是链路、交换机、流表等

资源标识符(resource identifiers)

URI是统一资源标示符,URL是统一资源定位符。URL是URI的子集,或者说是一种具体实现
对于REST API来说一个资源对应唯一的一个URI,REST通过URI来暴露资源,URI的设计的合理性和规范性十分重要

REST的约束条件与原则

  • 客户-服务器(Client-Server):用户接口和数据存储的分离;---通过客户端用户接口和服务器数据存储的分离,提高了客户端的便捷性,也提高了服务端的可伸缩性。由于实现了解耦,就能够允许客户端和服务端分组优化,彼此之间不受影响
  • 无状态(Stateless):要求每一个请求必须包含服务器处理该请求所需的所有信息;--- 提高了可见性和可靠性,由于服务器是无状态的,能够很方便的实现水平扩展,提高了可扩展性。 在RESTful的架构中,可以直接定位到服务器的资源,不依赖于服务器的会话状态,因此是无状态
  • 缓存(Cache):要求一个请求的响应中的数据标记为是否可缓存;如果可以,客户端可以重用相同请求的响应数据---减少了CS交互次数,提高了效率
  • 统一接口(Uniform Interface):核心特征,强调组件之间要有一个统一的接口;--- CS之间通信的方法必须是统一化的,例如标准的HTTP动作
  • 分层系统(Layered System):限制组件的行为,将架构分为若干等级的层;允许服务器和客户端之间的中间层,例如反向代理、API网关,可以代替服务器对客户端的请求进行回应,而对客户端而言是透明的,提高了系统的可扩展性,也增加了系统的复杂性
  • 按需代码(Code-On-Demand,可选):服务器可以提供一些代码或者脚本并在客户的运行环境中执行。

REST API的设计

REST API是基于HTTP协议进行设计的,由HTTP动词+URI组成,HTTP动词描述操作;URI是标识资源。

HTTP动词

image

资源的原型

  • 文档(Document):文档是资源的单一表现形式;
  • 集合(Collection):集合是资源的一个容器(目录),可以向里面添加资源(文档);
  • 仓库(Store):客户端管理的一个资源库,可以向仓库中新增资源或者删除资源,或者从仓库中获取资源;
  • 控制器(Controller):可以执行一个方法,支持参数输入,结果返回。

URI命名规范

  • 资源命名规范:

    • 文档(Document)类型的资源用名词单数命名
    • 集合(Collection)类型的资源用名词复数命名
    • 仓库(Store)类型的资源用名词复数命名
    • 控制器(Controller)类型的资源用动词命名
  • URI命名规范:

URI中有些字段可以是变量,在实际使用中可以按需替换,例如:
http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamId}/players/{playerId} 
其中:leagueId,teamId,playerId 是变量(数字,字符串等类型都可以)
  • URI格式规范

    • URI中分隔符“/”一般用来对资源层级的划分, ”/“不应该出现在URL的末尾;
    • URI中尽量使用连字符"-"代替下划线"_"的使用
      例如: http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
    • URI中统一使用小写字母
    • URI中不要包含文件(或脚本)的扩展名
      例如:不要出来.php或者.json之类的后缀名。
    • CRUD的操作不要体现在URI中
  • URI的query字段

作为查询的参数补充,以标示一个唯一的资源
作为过滤条件使用,例如:GET /users?role=admin 
作为资源列表分页标示使用,例如:GET /users?pageSize=25&pageStartIndex=50

HTTP响应状态

REST API相关的响应状态码

2xx:操作成功
3xx:重定向
4xx:客户端错误
5xx:服务器错误

常用状态码

200 (“OK”) :一般性的成功返回,不可用于请求错误返回;
201 (“Created”) :资源被创建;
202 (“Accepted”) :Controller控制类资源异步处理的返回,仅表示请求已经收到;
204 (“No Content”) :可能会出现在PUT、POST、DELETE的请求中;
303 (“See Other”) :返回一个资源地址URI的引用,但不强制要求客户端获取该地址的状态;
400 (“Bad Request”) :客户端一般性错误返回, 其它4xx的错误,也可以使用400,具体错误信息可以放在body中;
401 (“Unauthorized”) :认证错误;
404 (“Not Found”) :找不到URI对应的资源;
500 Internal Server Error:服务器处理请求时发生了意外;
503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

元数据设计

HTTP Headers
Content-Type :body的数据格式,如Content-type: application/json,表示主类型是application,数据格式是json
Content-Length :body 数据体的大小
Last-Modified :资源最后被修改的时间戳
ETag :服务器端资源版本的标示
Location :在响应header中使用
Cache-Control, Expires, Date : 通过缓存机制提升接口响应性能

标签:HTTP,URI,REST,API,设计规范,资源,客户端
来源: https://www.cnblogs.com/lht333/p/16701682.html

专注分享技术,共同学习,共同进步。侵权联系[81616952@qq.com]

Copyright (C)ICode9.com, All Rights Reserved.

ICode9版权所有