开发者必备——API设计问题

本文主要探讨RPC和RESTFul两种API风格的特点以及在开发中应该如何进行技术选型,截取了部分网上社区,文章关于API设计的想法和观点供读者参考取舍。

1,背景简述

API学名:应用程序接口(Application Programming Interface)

通俗的打个比方,人与人之间通过语言来交流,而程序和程序之间通过API来交流。

目前市场主流的API设计包括RPC,RESTFul,GraphQL等设计思路,关于API风格优劣,好坏众说纷纭,但客观来说:RPC资历最老,并沿用至今,RESTFul后来者居上,火了好大一阵,最新的GraphQL据说会在Githup下一版投入使用。API的选择问题丝毫不亚于跨端框架Flutter和RN的激烈斗争。但笔者坚持认为:软件开发没有银弹,技术终究会被历史裹挟,不断推进,但对于开发者来说,也许没有永恒的银弹,但在当下选择适合自己业务场景的技术却是举足轻重。

本篇文章主要探讨前两种API设计的优缺点以供读者进行技术决策的参考。

2,RPC以动词为核心

2.1 命名风格

RPC 形式的API通常是动宾结构:

getUserInfo,createUser,getUserById

由于接口的个性化需求,添加新功能时,API中可能会引入其他的动词或介词如By,With,create等等,这也是RESTFul征讨RPC的主要原因

  • 一是嫌它丑
  • 二是认为它不够通用(在服务端更新了之后,客户端也需要阅读文档,适应服务端)

3.1 常用实践

  • 面向接口编程

    在参数传递过程中使用接口而不是实现类,使程序更加灵活可扩展

    例如使用Map而不是HashMap,TreeMap,使用List而不是ArrayList,LinkedList

  • 方法重载

    通俗来讲,省去了方法名,使得API调用更加方便

3,RESTFul以名词为核心

“表述性状态转移”

3.1命名风格

/admin/users (查询用户)
/admin/users (新增用户)
/admin/users (更新用户)
/admin/users (删除用户)

虽然有点不太恰当,但RESTFul的以名词为核心的API风格其实就是把动词使用请求方法代替了,所谓的表述性状态转移实际上就是用请求方法屏蔽掉了API的部分实现。但不可否认的是,这样对于API的可读性的确有显著提高。

 @RequestMapping(value = "/user", method = RequestMethod.GET)
 @RequestMapping(value = "/user", method = RequestMethod.DELETE)

然而,RESTFul并不能很好适应API的复杂性,例如常见的登录注册功能使用RESTFul的风格难以对资源进行抽象。RESTFul对于单资源的增删改查的确可以实现API的升级,但由于其接口粒度过粗,对于多资源的查询操作难以设计出合理的API。

3.2 常用实践

  • 资源名使用复数

    不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。

  • 避免多级 URL(存在争议)

    获取某个作者的某一类文章
    GET /authors/12/categories/2
    
    GET /authors/12?categories=2
    
    ==============================
    查询已发布的文章
    GET /articles/published
    
    GET /articles?published=true
    

4,如何对RPC和RESTFul进行技术决策?

  • 可读性

    相对于RPC,RESTFul风格的API具有更强的可读性,更加利于理解

  • 兼容性

    RESTFul相对于RPC接口,粒度更大。

    RESTFul适合应用于开发API的增删改查,而RPC适合更加精细化可定制的业务场景

在实现开发接口API,RESTFul有更好的表现。

在实现业务系统,RPC具有更高的定制化能力。

5,关于API接口设计的一些讨论

参考文章

浅谈如何设计API

restful与rpc风格

REST与RESTFul API最佳实践

API 设计最佳实践的思考

RESTful API 最佳实践

(0)

相关推荐

  • Node.js仿知乎服务端-深入理解RESTful API

    ┃  ┃  ┃  ┣━6-2 Koa 自带的错误处理_batch.mp4! s9 D0 \9 ]+ u( O# N2 P+ R ┃  ┃  ┃  ┣━14-2 问题-答案模块二级嵌套的增删改查接口.m ...

  • 02 restful接口规范

    restful接口规范 接口规范:就是为了采用不同的后台语言,也能使用同样的接口获取到同样的数据如何写接口:接口规范是 规范化书写接口的,写接口要写 url.响应数据 注:如果将请求参数也纳入考量范围 ...

  • RESTful API、gRPC 和 GraphQL 有何不同,如何正确地做技术选型?

    转载自:EAWorld 前言: 架构师的主要活动是做出正确的技术决策.选择合适的API是一项重要的技术决策.那么今天就看看API的选择问题. 应用程序编程接口(API)是一种计算接口,它定义了多个软件 ...

  • php架构之路

    鉴于最近跟小伙伴聊了很多PHP架构发展方向的问题,相关技术整理了一下,也顺便规划了一下自己的2019年. 一.常用的设计模式以及使用场景 以下是我用到过的   工厂,单例,策略,注册,适配,观察者,原 ...

  • Python Flask 开发 web 指南01之创建你的第一个 RESTful APP

    上回,我们知道了 Flask 是一个 web 轻量级框架,可以在上面做一些扩展,我们还用 Flask 创建了 API,也说到了 REST API,今天咱们来玩一下 Flask-RESTful,体验一下 ...

  • 设计师必备的设计宝典!

    近期别致的广州恒大足球场"莲花"造型火遍设计圈地产圈,你以为这就够奇葩了吗?笑话!那今天让我来揭露设计界的反人类设计!!!只能用一个字形容 ,服!! 设计云线=地上挖洞?坐便池与洗 ...

  • 2021年,开发者必备的3款Kubernetes工具

    在过去几年,我们看到有大量工具被开发出来,用于简化在 Kubernetes 上的软件开发.正如生态系统中,优胜劣汰.适者生存一样,功能强大.操作便利的工具会不断壮大,反之,则不会被使用者接受.那么,2 ...

  • CAD插件神器排行榜第一位|CAD施工图设计大师必备顶级设计辅助,又名“正版海龍工具箱”?

    [食住玩3dmax插件神器冠军|导读] 一.3dmax插件神器|疯狂模渲大师50分钟怎么教学效果图视频教程: 二.CAD插件神器排行榜第一位|CAD施工图设计大师必备顶级设计辅助,又名"正版 ...

  • 一文详解 API 设计最佳实践

    架构之美 68篇原创内容 公众号 -     前言    - 良好设计的API = 快乐的程序员

  • 转型UI必备的设计工具

    转型UI设计需要知道哪些好用的UI设计工具? 平面设计行业竞争越来越激烈,内卷越来越严重,作为新人小白,很容易在面试的时候被别的候选人比下去.那么,是否考虑转型做UI设计师呢?如果转型去做UI设计,首 ...

  • uniapp后台api设计(微信user表)

    MySQL 创建数据库: CREATE  DATABASE [IF NOT EXISTS] <数据库名> [[DEFAULT] CHARACTER SET <字符集名>] [[ ...

  • 【控制工程师必备】设计和建造小型控制项目的步骤和技巧

    摘要 为了尽可能顺利地建立一个小型控制项目,应该考虑零件的订购和选用.系统的构建以及编程工作等方面的因素. 要建立一个能够正确运行的控制项目有时候会很贵而且耗费大量时间.即使是做一个小项目,例如计算机 ...

  • 一文详解API设计最佳实践

    一文详解API设计最佳实践

  • 架构必备「RESTful API」设计技巧经验总结

    [译者注]本文是作者在自己的工作经验中总结出来的RESTful API设计技巧,虽然部分技巧仍有争议,但总体来说还是有一定的参考价值的.以下是译文. 简单说一下代码重用 记得在Ken Rogers的M ...