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

1顶
1踩

编程语言

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

2015-11-19 19:16 by 副主编 mengyidan1988 评论(3) 有17578人浏览
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集成两个应用...

  • 人力资源经理绩效考核表.xls

    人力资源经理绩效考核表

  • 智慧环卫管理平台建设方案Word(211页).docx

    一、智慧环卫管理平台的建设背景与目标 智慧环卫管理平台的建设源于对环卫管理全面升级的需求。当前，城管局已拥有139辆配备车载GPS系统、摄像头和油耗传感器的环卫车辆，但环卫人员尚未配备智能移动终端，公厕也缺乏信息化系统和智能终端设备。为了提升环卫作业效率、实现精细化管理并节省开支，智慧环卫管理平台应运而生。该平台旨在通过信息化技术和软硬件设备，如车载智能终端和环卫手机App，实时了解环卫人员、车辆的工作状态、信息和历史记录，使环卫作业管理透明化、精细化。同时，平台还期望通过数据模型搭建和数据研读，实现更合理的环卫动态资源配置，为环卫工作的科学、健康、持续发展提供决策支持。 二、智慧环卫管理平台的建设内容与功能 智慧环卫管理平台的建设内容包括运行机制体制建设、业务流程设计、智慧公厕系统建设、网络建设、主机和储存平台需求、平台运维管理体系、硬件标准规范体系以及考核评价体系等多个方面。其中，智慧公厕系统建设尤为关键，它能实时监控公厕运行状态，保障公厕的清洁和正常运行。平台建设还充分利用了现有的电子政务网络资源，并考虑了有线和无线网络的需求。在功能上，平台通过普查、整合等手段全面收集环卫车辆、企业、人员、设施、设备等数据，建立智慧环卫基础数据库。利用智能传感、卫星定位等技术实现环卫作业的在线监管和远程监控，实现对道路、公共场所等的作业状况和卫生状况的全面监管。此外，平台还建立了环卫作业网格化管理责任机制，实现从作业过程到结果的全面监管，科学评价区域、部门、单位和人员的作业效果。 三、智慧环卫管理平台的效益与风险规避 智慧环卫管理平台的建设将带来显著的环境、经济和管理效益。环境方面，它将有力推进环境卫生监管服务工作，改善环境卫生状况，为人民群众创造更加清洁、卫生的工作和生活环境。经济方面，通过智慧化监管，大大降低了传统管理手段的成本，提高了监管的准确性和效率。管理方面，平台能够追踪溯源市民反映的问题，如公厕异味、渣土车辆抛洒等，并找到相应的责任单位进行处置，防止类似事件再次发生。同时，平台还拥有强大的预警机制功能，能够在很多环卫问题尚未出现前进行处置。然而，平台建设也面临一定的风险，如部门协调、配合问题，建设单位选择风险以及不可预测的自然灾害等。为了规避这些风险，需要加强领导、统一思想，选择优秀的系统集成商承接项目建设，并做好计算机和应用系统的培训工作。同时，也要注意标准制定工作和相关法律法规的制定工作，以保证系统建设完成后能够真正为环卫管理工作带来便利。

  • apache-parent-10-14.el7.x64-86.rpm.tar.gz

    1、文件内容：apache-parent-10-14.el7.rpm以及相关依赖 2、文件形式：tar.gz压缩包 3、安装指令： #Step1、解压 tar -zxvf /mnt/data/output/apache-parent-10-14.el7.tar.gz #Step2、进入解压后的目录，执行安装 sudo rpm -ivh *.rpm 4、安装指导：私信博主，全程指导安装

  • 用于卫星通信的CTS天线

    用于卫星通信的圆极化CTS天线研究

  • 人事档案登记及查询系统.xlsx

    人事档案登记及查询系统

Global site tag (gtag.js) - Google Analytics