专栏首页机器学习与系统[翻译]RESTful API模式系列二:API设计者的职责

[翻译]RESTful API模式系列二:API设计者的职责

在完全深入RESTful API设计之前,详细了解RESTful API设计者的工作细节很重要。

APIs之间不是孤立的,对于API中已经存在的应用或者服务的API,新的API要和它们在功能上独立开来。在我看来,API设计者的职责是双重的:

  1. 足够理解新建API在应用中的重要细节,这样你就能决定哪些功能需要暴露、如何暴露,以及哪些功能可以排除。
  2. 对API中的功能建模,要能解决出现的所有使用场景,同时尽可能遵守RESTful原则。

RESTful API设计中涉及到3个不同的组件:应用、API代码和客户端。下图描述了组件间的相互关系:

应用

应用和为它提供的API之间要相互独立。也许应用是GUI程序,你需要为它提供可编程接口。也许应用只能通过你设计的API访问。

和其它任何应用一样,需要设计API的应用也有它自己的状态。“状态”是动态的,执行很多操作后状态会改变。状态和状态上的操作,应该被建模并暴露到API中

理解应用状态的最简单方法是把它描述成应用数据模型(application data model),可以表示成实体-关系图(ER图)。实体-关系图能列出应用状态中实体的细节,以及它们间的关系。

一些情景中,很容易创建实体-关系图。假设一个web应用把所有状态存在数据库中,我们很容易从数据的schema中得到关系图。其它一些没有严格定义的情景下,API设计者的工作会难一些。这时,为应用创建ER图就真的很有用。对你来说这是难得的锻炼机会,它帮助你更好地理解应用。更重要的是,它会帮你设计出更好的RESTful API。我们一会详细讨论这个。以后的例子中,我都假设我们已经有了实体-关系图(ER diagram)。

除了理解应用的状态和状态上的操作外,你还需要应用程序的入口(entry point),它让你能获取和更改应用状态。这个“入口”完全由应用决定,可以有多种形式。我们把这个入口称为应用程序接口( application interface),它的正式称呼是API。不同的是接口不用于外部消费甚至完全没有文档记录(译者注:正规软件开发中代码规范也是要求写API文档的)。为了不产生疑惑,我们不会把接口称为API,API这个术语保留给我们将要设计的RESTful API。

API代码

API代码的任务是通过应用接口获取应用的状态,同时提供状态上的操作,把应用接口暴露成RESTful API。在应用程序接口和RESTful API之间有一个转换步骤:适配应用数据模型,并且符合RESTful风格。

转换的结果是形成RESTful风格的资源、资源上的操作以及资源之间的关系。(译者注:API中只有状态的概念,RESTful后形成资源的概念)我们把这些称为RESTful资源模型(RESTful resource model)。

资源是任何RESTful API的基础,我们会在resources中详细介绍。现在,我们只需要把资源理解成ER图中的实体(这也是为什么应用中没有实体时我建议你画ER图)。

资源间的关系通过超链接表示。这一点也是设计RESTful API的基本原则(fundamental principles)。资源通常响应有限的操作(通常4个),这也是RESTful架构的第二个风格。

当把应用模型对象转换成RESTful里的资源时,下面两个工具函数很有用:

  • to_resource():从应用模型中获取一个对象,然后转换成资源。
  • from_resource():把资源转换成应用模型中的对象。

后面不会再讨论这两个函数,当应用数据模型和资源模型相似时,函数会很简单;不相似的话会很复杂。

客户端

客户端通过标准HTTP协议消费RESTful API。理论上,RESTful API也可以在其它协议之上提供。但是,由于HTTP协议非常广泛,把RESTful API映射到另一种协议在真实场景中意义不大。因此,本文仅限于用HTTP协议相关术语描述RESTful协议。

客户端通常使用HTTP库来访问RESTful API。HTTP已经成为一个相对复杂的协议,许多目标平台/语言都有优秀的库。因此使用这些库很合理。

在某些情况下,可能有必要在HTTP库之上使用通用的REST库。但是,由于RESTful API中有一些不一致的约定,因此通用的REST库适用于特定情况下的API。

译者说

本篇介绍了RESTful中的三大组件:应用、API代码和客户端。读者要理清状态资源之间的对应关系。RESTful API可以有很多实现方式,因为HTTP应用广泛,有非常多的库,所以RESTful API通常用HTTP协议实现。

本文分享自微信公众号 - 机器学习与系统(aimlsystem),作者:adolphlwq

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2017-03-07

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • RESTful API模式系列三:资源

    资源是任何RESTful API中的基本概念。资源是对象,包括类型、关联的数据、资源间的关系以及资源上的操作集合。它和面向对象编程语言中的对象类似,不同点在于资...

    陆道峰
  • API 接口渗透测试

    远程过程调用(英语:Remote Procedure Call,缩写为 RPC)是一个计算机通信协议。该协议允许运行于一台计算机的程序调用另一台计算机的子程序,...

    HACK学习
  • C#开发BIMFACE系列2 二次开发流程

      BIMFACE 平台是一个对外开放的平台,建筑行业的相关公司、软件公司或者有 BIM 业务需求的公司都可以注册成为开发者并使用其提供的强大功能。

    张传宁IT讲堂
  • DRF系列总结一:DRF是啥?为啥子要用?

    目前组内很多项目都在用Django REST framework(简称DRF)来构建Restful WebApi,并推广到了许多实习生同学和外部服...

    高木工
  • 人脸识别、情感分析,开发者必备50个机器学习API|值得收藏

    该清单按照字母排序,对 API 的概述是基于对应官网所提供的信息整合而成。要是大家发现该清单中错过了某些当前流行的 API,可以在评论中告知。

    BestSDK
  • Spring Boot从零入门5_五脏俱全的RESTful Web Service构建

    这一节我们正式进入Spring Boot的WEB服务开发,在WEB服务中,不可缺少的我们需要去提供API出来,那么就少不了设计API,而当前流行的一套API设计...

    别打名名
  • 2018 最新机器学习 API 推荐清单,快给 APP 加点智能

    本篇基于 2017 年的推荐清单做了一些改进——去除了一些不再进行维护的 API,并且更新了一些新的 API。主要覆盖如下方向:

    AI研习社
  • RESTful API教程:学习关键的Web服务设计原则

    原题:RESTful APIs tutorial: Learn key web service design principles

    yuanyi928
  • [译文和个人分析]REST vs RPC - RESTful究竟是什么?

    好烦啊,分不清REST RPC RESTful的区别,所以只能翻译一篇谷歌的文章,括号中是我的补充

    ydymz
  • Django+Vue开发生鲜电商平台之4.Restful API和Vue介绍

    Github和Gitee代码同步更新: https://github.com/corleytd/Django_Fresh_Ecommerce; https:...

    cutercorley
  • Spring+SpringMVC+MyBatis+easyUI整合进阶篇(一)设计一套好的RESTful API

    写在前面的话 看了一下博客目录,距离上次更新这个系列的博文已经有两个多月,并不是因为不想继续写博客,由于中间这段时间更新了几篇其他系列的文章就暂时停止了,如今已...

    程序员十三
  • 前后端分离开发思路探讨

    但是毕竟要从前后端不分变为前后端分离,思维的变化还是比较大的,因此,今天我们就再来说说一说这个话题。

    江南一点雨
  • Python之初识Web,打造属于你的个人品牌!

    在上一期关于对Python的介绍中讲到Python在Web开发、数据科学、爬虫系统、机器学习、自动化运维和测试中有着较为广泛的应用。不了解的朋友可以查看‘Pyt...

    灰小猿
  • 避免自己写的 url 被diss!建议看看这篇RestFul API简明教程!

    大家好我是 Guide 哥!这是我的第 210 篇优质原创!这篇文章主要分享了后端程序员必备的 RestFul API 相关的知识。

    Guide哥
  • xwiki功能-XWikiRESTfulAPI

    XWiki通过一个基于HTTP语义的API来访问几乎每一个元素,即RESTful API。在本页中,你会发现这个API的所有细节,并利用这个API充分发挥它的优...

    lovelife110
  • RESTful源码学习笔记之RPC和 RESTful 什么区别

    REST,即Representational State Transfer的缩写。翻译过来是表现层状态转换。 如果一个架构符合REST原则,就称它为RESTfu...

    Jetpropelledsnake21
  • REST 入门介绍

    dudu的 HttpClient + ASP.NET Web API, WCF之外的另一个选择 讨论的人很多,说明RESTful API也开始在.NET 社区中...

    张善友
  • 【史上最全】国内外常用精品API接口汇总

    API是获取网络服务最便捷的方式,合理地使用API开发项目可以大大提高开发效率,把精力都集中在程序的业务逻辑之上,避免重复造轮子。推荐给大家个人觉得很赞的第三方...

    凯哥Java
  • Retrofit解析1之前哨站——理解RESTful

    本篇文章是Retrofit的前哨站——理解RESTful。因为retrofit是基于RESTful架构。所以在讲解Retrofit之前,先来复习一下RESTfu...

    隔壁老李头

扫码关注云+社区

领取腾讯云代金券