资讯频道 → 编程语言
阅读更多

1顶
1踩

编程语言

转载新闻 创建 REST API 的最佳入门教程

2015-11-19 19:16 by 副主编 mengyidan1988 评论(3) 有17655人浏览
java rest API 开放平台
你以前可能听说过API 和REST,然后你就会想:“这些都是什么东西？”。也许你已经了解过一些这方面的知识，但却不知道从何入手。在这个教程中，我将会诠释REST的基础以及如何给应用创建一个API（包括认证授权）

什么是API?

API是Application Programming Interface（应用程序界面）的缩写，它是拿来描述一个类库的特征或是如何去运用它。你个人收藏的类库也许包含有可用功能的“API文档”，那些必需的参数我们该怎么称呼它们？诸如此类等等。

然而，如今很多人参考API文档时，他们常常参考一种可能会通过网络分享你的应用数据HTTP API，例如，Twitter提供一个API能让用户在特定的格式下请求推文，以便用户方便导入到自己的应用程序中。这就是HTTP API的真正强大之处。它能够从多个应用程序中混搭数据到混合应用程序中，或是创建一个能增强使用他人应用体验的应用程序。

这样说吧，比如说我们有一个可以允许我们查看（view），创建（create），编辑（edit）以及删除（delete）部件的应用程序。我们可以创建一个可以让我们执行这些功能的HTTP API: 
http://example.com/view_widgets
http://example.com/create_new_widget?name=Widgetizer
http://example.com/update_widget?id=123&name=Foo
http://example.com/delete_widget?id=123

当人们开始去实现他们自己的API接口时，问题就出现了。竟然没有一个标准的方法来命名URL，人们总是要参考API才得知它是如何运作的。一个API中可能命名一个URL为/view_widgets，但是另一个API可能就命名成/widgets/all.

不用担心！REST帮你搞定这些混乱！

什么是REST呢?

REST是Representational State Transfer的缩写，它是由罗伊·菲尔丁(Roy Fielding)t提出的，是用来描述创建HTTP API的标准方法的，他发现这四种常用的行为（查看（view），创建(create)，编辑(edit)和删除(delete)）都可以直接映射到HTTP 中已实现的GET,POST,PUT和DELETE方法。

HTTP 中的8中不同的方法：
引用

GET
POST
PUT
DELETE
OPTIONS
HEAD
TRACE
CONNECT

大多数情况下，当你在使用你的浏览器的点点看看的时候，其实只用到HTTP的GET方法。GET方法是在你向因特网请求资源的时候才会用到的。当你提交一个表单时，你就会经常用到POST方法来回传数据到网站上。至于其他的几种方法，某些浏览器可能根本就没有去完全实现它们。但是，如果是供我们使用的话，就没什么问题。问题是我们有很多要选择去帮助描述这四大行为的HTTP方法，我们将会用到那些已经知道如何去使用这些不同的HTTP方法的客户端类库。

REST例子：

让我们来看下几个让API表述性状态转移化的例子，就用我们之前说的那几个部件来解释：

如果我们想要查看所有部件，URL将是这个样子： 
GET http://example.com/widgets

用POST方法新建一个用来发出请求数据的部件： 
POST http://example.com/widgets
Data:
    name = Foobar

用GET方法查看一个简单的部件，我们从指定的部件id中获取： 
GET http://example.com/widgets/123

用PUT方法发送新数据来更新部件： 
PUT http://example.com/widgets/123
Data:
    name = New name
    color = blue

用DELETE方法来删除部件： 
DELETE http://example.com/widgets/123

解剖REST URL：

你可能已经注意的前面的几个例子，REST URL使用着一套一致的命名方法。当你跟API交互时，你几乎经常操作一些对象。在我们的例子中，我们讲的是部件。在REST中，我们称之为Resource。URL的第一部分经常是这个资源的复数形式： 
/widgets

当我们参考收集的资源时（list all：列出所有 和add one：新增一个），这将会经常用到。当你用到一些特殊的资源的时候，你就会给URL增加一个id，这个URL在你想要“view”，“edit”和“delete”特殊资源的时候会被使用。

嵌套资源：

如果说，我们的部件有很多用户使用，URL的结构又将会是怎样的呢？

列出所有用户 
GET /widgets/123/users

新增一个用户 
POST /widgets/123/users
Data:
    name = Andrew

嵌套资源在URL里是完全兼容的，但是超过两层嵌套就不是很好的方法了。其实这根本不需要，因为你完全可以以ID的形式参考到那些嵌套资源，总比嵌套在父类中好。例如： 
/widgets/123/users/456/sports/789

这可以替换为： 
/users/456/sports/789

甚至可以替换成这样： 
/sports/789

HTTP 状态码：

REST的另一重要部分就是为既定好请求的类型来响应正确的状态码。如果你对HTTP状态码陌生，以下是一个简易总结。当你请求HTTP时，服务器会响应一个状态码来判断你的请求是否成功，然后客户端应如何继续。以下是四种不同层次的状态码：
  • 2xx = Success（成功）
  • 3xx = Redirect（重定向）
  • 4xx = User error（客户端错误）
  • 5xx = Server error（服务器端错误）

以下是一些最重要的状态码：
请求成功的状态码：
  • 200 – OK (默认的)
  • 201 – Created（已创建）
  • 202 – Accepted (已接受：常用语删除请求)

客户端错误状态码：
  • 400 –请求出错（语法格式有误或服务器无法理解此请求）
  • 401 – 未授权(需要登录)
  • 404 – 找不到 (找不到所请求的文件或脚本)
  • 405 – 不允许此方法(错误的 HTTP方法)
  • 409 – 冲突 (IE尝试以PUT请求创建相同的资源时)

API响应格式：

当你请求HTTP时，你可以请求你想要接收的格式。例如，请求一个网页，你想以HTML的格式请求，或者如果你想要下载一张图片，返回格式应该是图片的格式。然而，响应请求格式是服务器的职责。

如今，JSON 已经快速发展成为REST API选择的格式，它有一个轻量级的、可读性又很高的语法，以致其很容易操作。所以，当使用我们API的用户按他们想要的格式发出请求和指定JSON时。 
GET /widgets
Accept: application/json

我们的API将会以JSON的格式返回一批部件： 
[
  {
    id: 123,
    name: 'Simple Widget'
  },
  {
    id: 456,
    name: 'My other widget'
  }
]

要是用户请求一个我们没有实现的方法的格式时，我们又该怎么办呢？你大可以抛出一些错误的类型。但我建议你将JSON格式作为你的标准响应格式，因为这是开发者想要的格式。没理由去支持其他的格式，除非你已经有一个可支持的API。

创建一个REST API：

事实上，创建一个REST API是超出此教程范围的，因为它是有特定语言的。但我将以Ruby（一种为简单快捷的面向对象编程而创的脚本语言）的方式给出一个简易例子，它使用一个叫Sinatra的类库（不懂得可以自行百度）。 
require 'sinatra'
require 'JSON'
require 'widget' # our imaginary widget model

# list all
get '/widgets' do
  Widget.all.to_json
end

# view one
get '/widgets/:id' do
  widget = Widget.find(params[:id])
  return status 404 if widget.nil?
  widget.to_json
end

# create
post '/widgets' do
  widget = Widget.new(params['widget'])
  widget.save
  status 201
end

# update
put '/widgets/:id' do
  widget = Widget.find(params[:id])
  return status 404 if widget.nil?
  widget.update(params[:widget])
  widget.save
  status 202
end

delete '/widgets/:id' do
  widget = Widget.find(params[:id])
  return status 404 if widget.nil?
  widget.delete
  status 202
end

API授权认证:

在一般的网页应用中，认证操作是经常要接收用户名和密码的，然后在session中保存用户ID。用户的浏览器就会保存会话中的ID到cookie中。当用户在网站上访问需要认证授权的页面时，浏览器就会发送cookie，应用程序就会查找seesion会话中的ID（如果它没有失效的话），由于用户的ID保存在seesion中，用户就可以浏览页面了。

用这个API，就可以使用seesion会话保存用户记录,但这毕竟不是最好的方法。有时候，用户想直接访问API，或是用户想自己授权其他应用程序去访问这个API。

解决方法是在认证的基础上使用秘钥。用户输入用户名和密码以登录，应用程序就以一个特殊秘钥返回给用户以备后续之需。这个秘钥可以通入应用程序，以至于如果用户想要选择拒绝应用更进一步的接入时，可以撤回这个秘钥。

其实，网上已经有一个做上面这件事的很流行的标准方式，叫做OAuth（开放授权：是一个开放标准，允许用户让第三方应用访问该用户在某一网站上存储的私密的资源（如照片，视频，联系人列表），与以往的授权方式不同之处是OAUTH的授权不会使第三方触及到用户的帐号信息（如用户名与密码），即第三方无需使用用户的用户名与密码就可以申请获得该用户资源的授权，因此OAUTH是安全的。），特别的，标准第二版的OAuth。网上有很多非常好的实现OAuth的资源，所以我才说那是超出此教程范围的。如果你正在使用Ruby，这里有一些帮你解决大多数工作的很好的类库，比如OmniAuth 。

花了那么多时间给你们讲解这个教程，希望对你们有所帮助。

本文转自：http://codecloud.net/
1
顶
1
踩
评论 共 3 条 请登录后发表评论
3 楼 xfxlch 2016-01-06 11:04
Janyue 写道
我一直以为API是应用程序接口了，楼主普及知识及时啊！！！！！！！

interface当然是接口啦，java中接口定义用过吧
2 楼 richardbigzhou 2015-11-25 09:20
例子代码是java的？还是ruby的？没看懂
1 楼 Janyue 2015-11-23 18:17
我一直以为API是应用程序接口了，楼主普及知识及时啊！！！！！！！

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

  • SOFA：创建REST API的最佳方法-从GraphQL Server生成RESTful API

    创建REST API的最佳方法（是GraphQL）。 安装 yarn add sofa-api # or npm install sofa-api 入门 这是不依赖框架的完整示例，但也可以与任何框架集成： import http from 'http' ; import getStream from 'get-...

  • REST API 最佳入门指南

    在这个教程中，我将会诠释REST的基础以及如何给应用创建一个API（包括认证授权）。 什么是API? API是Application Programming Interface（应用程序界面）的缩写，它是拿来描述一个类库的特征或是如何去运用它。你...

  • REST API 的最佳入门教程

    如果你看到这里，你以前可能听说过...在这个教程中，我将会诠释REST的基础以及如何给应用创建一个API（包括认证授权） 什么是API? API是Application Programming Interface（应用程序接口）的缩写，它是拿来描述一...

  • NestJS-RestAPI-starter：完整的入门包基于REST API的NodeJS

    Node JS REST API入门包 这是基于REST API NodeJS的入门包，用于使用企业体系结构快速开发高级API服务。 安装 npm install 用法 开发模式 npm run start 生产 npm run start:prod 运行测试 npm run test 特征： ...

  • REST API 设计最佳实践

    “应用程序编程接口”或 API 是指各种软件服务之间的通信通道。传输请求和响应的应用程序分别称为客户端和服务器。

  • 教你一招！用Python和Flask创建REST API！

    REST API 简介注意，这里只是对REST API 的简单介绍，起到抛砖引玉作用，更加深入内容不在本次学习范围内，感兴趣的小伙伴可以查看相关资料深入学习。此外本号接受该领域的投稿，欢迎联系云朵君！APIAPI，全名...

  • python rest api 测试_使用Python + Pytest + Allure进行Rest API测试新手入门教程

    MP4 |视频：h264，1280×720 |音频：AAC，44.1 KHz，2通道类型：电子学习|语言：英语|会期：166个讲座(16h 3m)|大小：5.8 GB最适合新手|Rest API测试|自动化PythonJson验证|PyTest实施您将学到的内容：**准备好设计...

  • 在 .NET Core 中构建 REST API

    翻译自 Camilo Reyes 2020年8月26日的文章《Build a REST API in .NET Core》[1]REST API 可以使用简单的动词（如 POST、PU...

  • 使用Protobuf推动微服务和REST API的开发

    一些项目描述如下： Catalog.Client：.NET Standard项目，带有用于C＃的微服务的客户端库 Catalog.Models：.NET Standard项目以及微服务的Dto、请求和响应消息 Catalog.RestApi：具有微服务Rest API的AspNetCore项目...

  • symfony_4_jwt_restapi_demo:使用JWT令牌PHP Symfony 4 REST API示例

    它是在考虑最佳REST API惯例的情况下创建的。 REST API交互或多或少遵循此出色文章提供的指南/摘要： : 关于项目本身。 想到了一些想法，例如瘦控制器和TDD方法（该项目主要是通过首先创建测试，然后使用红绿重构...

  • 用 PHP 连接上 Office 365 REST API 进行操作入门

    Office 365 简单说就是云中的 ... Office 365 REST API 包含了对以下数据的操作： Exchange Online 的邮件（Mail）、日历（Calendar）、联系人（Contact）、SharePoint Online 和 OneDrive for Business 的文件和文件

  • rest api_如何使REST API向后兼容

    RESTful API是符合REST约束的API。 您可以使用许多不同的编程语言来构建RESTful API。 保持API不同版本之间的向后兼容性对于确保API与使用该API的所有客户端保持兼容至关重要。 本文讨论了如何在RESTful API中...

  • es6-express-mongoose-starter：:fire:用ES6编写的Express和Mongoose的Node.js入门包。 通过Express连接到MongoDB实例的基于Express的示例REST API

    它包含一个示例REST API，用于连接到MongoDB的虚拟待办事项，并使用Mocha / Chai进行单元测试。 文件和应用程序组织的最佳实践 准备使用ES6构建系统 使用Eslint进行代码整理 REST API连接到MongoDB的示例（通过...

  • jenkins 构建api_构建开发人员友好的REST API的最佳实践

    jenkins 构建apiREST APIs are probably the simplest way to integrate two applications over the Internet. Most web developers have integrated with or built them. REST API可能是通过Internet集成两个应用...

  • 外加热强制循环蒸发器装配图（CAD).rar

    外加热强制循环蒸发器装配图（CAD).rar

  • 数控车床纵向进给系统设计.zip

    数控车床纵向进给系统设计.zip

  • vault_side_off_ominous.png

    j

  • 爬虫 bangumi名称和评论数

    爬虫 bangumi名称和评论数

  • 基于SpringBoot的垃圾分类回收系统(源码+数据库+万字文档)526

    基于SpringBoot的垃圾分类回收系统，系统包含两种角色：管理员、用户主要功能如下。 【用户功能】 首页：浏览垃圾分类回收系统信息。 个人中心：管理个人信息，查看历史记录和订单状态。 运输管理：查看运输信息，垃圾回收的时间和地点。 公告管理：阅读系统发布的相关通知和公告。 垃圾回收管理：查看垃圾回收的信息，回收类型和进度。 垃圾出库申请管理：提交和查看垃圾出库申请的状态。 【管理员功能】 首页：查看垃圾分类回收系统。 个人中心：管理个人信息。 管理员管理：审核和管理注册管理员用户的信息。 用户管理：审核和管理注册用户的信息。 运输管理：监管和管理系统中的运输信息。 公告管理：发布、编辑和删除系统的通知和公告。 垃圾回收管理：监管和管理垃圾回收的信息。 垃圾出库申请管理：审批和管理用户提交的垃圾出库申请。 基础数据管理：管理系统的基础数据，运输类型、公告类型和垃圾回收类型。 二、项目技术 编程语言：Java 数据库：MySQL 项目管理工具：Maven 前端技术：Vue 后端技术：SpringBoot 三、运行环境 操作系统：Windows、macOS都可以 JDK版本：JDK1.8以上都可以 开发工具：IDEA、Ecplise、Myecplise都可以 数据库: MySQL5.7以上都可以 Maven：任意版本都可以

Global site tag (gtag.js) - Google Analytics