HTTP Methods 和 RESTful Service API 设计
含义:
- HTTP Methods:也叫 HTTP Verbs,HTTP Methods 可以翻译成 HTTP 方法。它们是 HTTP 协议的一部分,主要规定了 HTTP 如何请求和操作服务器上的资源,常见的有GET,POST等。
- API:Application Programming Interface 应用程序接口,RESTful API,这类API是通过 HTTP 协议 URL 形式暴露给其它系统或者模块调用,比如,一个获得用户所有评论的 API 可能像这样:https://api.server-name.com/user-id/comments
HTTP Methods 一共有九个,分别是 GET,HEAD,POST,PUT,DELETE,TRACE,OPTIONS,CONNECT,PATCH
RESTful API 设计中,常用的有POST,GET,PUT,PATCH 和 DELETE,分别对应对资源的创建,获取,修改,部分修改和删除操作。
Methods的用途和返回值约定
| HTTP Methods | 操作方式(CRUD) | 获取多个资源(/books)返回结果 |获取单个资源(/books/id) 返回结果
/books?page=3
| 200 (OK)<br />在Body中返回对应id的book<br /><br />404 (Not Found) <br />如果没有对应数据,或者id格式不对 || DELETE| 删除数据 Delete| 404 (Not Found)<br />一般直接返回404 除非你真的想删除全部集合可返回200 |200 (OK)
404 (Not Found) 如果id格式不正确或者没有找到 |
HTTP Methods 使用详细说明
- 客户端调用:客户端把要创建的数据放在HTTP请求的Body中,比如Body数据是{title: "Are your lights on", author: "Donald C. Gause"}之后发送 HTTP POST 请求到
https://api.server.com/books
- 服务端实现
- 服务端在收到客户端 POST 来的数据时,根据POST URL,发现应该创建books数据。
- 之后获取 body 里面的内容来创建一条新 book 记录并保存,如果一切正常,返回201表示创建成功。
- 返回时将 HTTP Header 'Location' 值设置为https://api.server.com/books/new-created-book-id
- 客户端可以获得该条刚创建数据的 Unique ID,方便在需要进一步操作时使用
注意:POST API 不是一个数据安全和幂等性操作,如果客户端多次调用同样的 API 会导致多条数据被创建,这些数据除了 ID 不同其他属性都相同。
举例:
POST https://api.server.com/books
POST https://api.server.com/books/123456/comments
GET
一般用于读取数据,即获取资源。成功调用 GET API 会返回相应的数据。如果请求的数据不存在可返回404(Not Found)或者由于参数不正确的原因可以返回400(Bad Request)
- 客户端调用:客户端只要简单发送一个 HTTP GET 请求到相应的 URL 即可,请求URL 中可以带上有关参数用来对数据进行条件过滤,如:GET https://api.server.com/books?author=gause
- 服务端实现:服务端在收到相应的请求之后根据 URL 判断应该返回什么类型的数据,并且根据 URL 参数对数据进行过滤后在放在 Body 中返回给客户端。GET 可以返回一个集合,类似数组的形式。如:
如果客户端只请求一条数据 GET https://api.server.com/books/000,应该返回对应ID的数据即可:
注意:GET操作是数据安全和具有幂等性的操作,也就是多次调用GET应该返回相同的数据(期间没有修改操作的前提下),并且不会导致任何数据的破坏性修改。
API举例:
GET https://api.server.com/books/123456
GET https://api.server.com/books/123456/comments
GET https://api.server.com/books/123456/comments/id001
GET https://api.server.com/books?author=gause
客户端调用:POST 调用方式几乎相同,比如要修改的数据是{id: "book-id-000", title: "Are your lights on", author: "Donald C. Gause"}
客户端发送 HTTP PUT 请求到https://api.server.com/books
。和POST不同的是,该操作会带上数据的 UID,用来定位具体要修改的这一条数据,方便后续操作。也有的设计会把ID放在URL中https://api.server.com/books/book-id-000
,这样要修改的Body中的数据可以不用包含ID
服务端实现:如果更新成功 PUT API 应该返回200。如果 PUT 请求的 body 中没有任何信息则返回204, 如果id没有找到或id格式不正确,返回404。和POST不同的是该 API 没有必要在Header中更新刚创建数据ID URL,因为我们是在修改该条数据,其 ID 之前已经被客户的获取。
API举例:
PUT https://api.server.com/books/123456/comments/id001
{title: "Are your lights on"}
只包含部分要修改的数据HTTP Methods 和 RESTful Service API 设计的更多相关文章
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- RESTful及API设计(原)
RESTful是一种架构风格,是由Fielding博士在自己的博士论文中提出并详细论述的. 它是用于指导web系统设计的,而指导API设计只是它的一小部分功能而已,如果只用它指导API设计就太大材小用 ...
- RESTful Service API 常见问题解决方案
REST 风格的优秀设计应该像下面这些: - GET /users 获取所有用户 - GET /users/1234 获取ID为1234的用户 - POST /users 创建一个新用户 - PUT ...
- 我所理解的RESTful Web API [设计篇]【转】
原文:http://www.cnblogs.com/artech/p/restful-web-api-02.html <我所理解的RESTful Web API [Web标准篇]>Web服 ...
- 我所理解的RESTful Web API [Web标准篇]
REST不是一个标准,而是一种软件应用架构风格.基于SOAP的Web服务采用RPC架构,如果说RPC是一种面向操作的架构风格,而REST则是一种面向资源的架构风格.REST是目前业界更为推崇的构建新一 ...
- RESTful Web API 实践
REST 概念来源 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备...). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通 ...
- 基于MVC的RESTFul风格API实战
基于MVC的RESTful风格的实现 1.RESTful风格阐述 REST服务是一种ROA(Resource-Oriented Architecture,面向资源的架构)应用.主要特点是方法信息存在于 ...
- RESTFul API设计指南及使用说明
RESTFul API设计指南及使用说明 一. 协议 API与用户的通信协议,使用HTTP协议. 二. 域名 应尽量将API部署在专用域名之下(http://api.example.com) 也可以将 ...
- (转)RESTful API 设计最佳实践
原文:http://www.oschina.net/translate/best-practices-for-a-pragmatic-restful-api 数据模型已经稳定,接下来你可能需要为web ...
随机推荐
- hdu-6435
Problem J. CSGO Time Limit: 4000/2000 MS (Java/Others) Memory Limit: 524288/524288 K (Java/Others ...
- Utils--Cookie工具类
Utils--Cookie工具类 package com.taotao.manage.util; import java.io.UnsupportedEncodingException; import ...
- group by 错误
出现错误: which is not functionally dependent on columns in GROUP BY clause; this is incompatible with s ...
- Linux stress CPU的测试方法
一.stress工具安装:1.获取stress源码安装包(stress-1.0.4.tar.gz)3.解压并安装 [root@localhost /]#cd /tmp/ [root@localhost ...
- openstack安装指南和在centos7上的安装指南
openstack安装指南官网:http://docs.openstack.org/project-install-guide/newton/ openstack在centos7上的安装指南官网:ht ...
- gradle set
gradle安装 1◆ gradle下载 http://services.gradle.org/distributions/ 2◆ 配置环境 =====>D:\envs\grad ...
- 解决win10打开组策略弹出管理模板对话框问题
今天win10企业版更新完系统,打开组策略编辑器时弹出管理模板对话框问题 1.问题描述 打开组策略编辑器时弹出管理模板对话框问题 2.解决方法 1)window+x 打开命令提示符(管理员) 2)输入 ...
- 逆袭之旅DAY17.东软实训.Oracle.存储过程
2018-07-13 09:08:36
- Win10系列:VC++ 定时器
计时器机制俗称"心跳",表示以特定的频率持续触发特定事件和执行特定程序的机制.在开发Windows应用商店应用的过程中,可以使用定义在Windows::UI::Xaml命名空间中的 ...
- Win10系列:JavaScript综合实例3
实现主页面的功能之后,接下来实现分类页面.分类页面中显示一种菜肴类别的详细信息,包括类别名称.图片.描述信息以及属于该类别的一些菜肴.在pages文件夹中添加一个名为classDetail的文件夹,并 ...