Rails RESTful API 构建实战Kittens API 项目全流程解析附 Flickr API 调用入门【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum本篇文章围绕开源课程仓库 cu/curriculum 中 Ruby on Rails 课程的 Kittens API 项目展开带你完成两件事先借助 Flickr 官方文档与 API Explorer 熟悉第三方 RESTful API 的调用套路再亲手搭建一个既能输出 HTML 页面、又能通过 JSON 对外提供数据的 Rails RESTful API。读完本文你将掌握 REST 请求格式、respond_to按格式渲染、HTTParty发起带Accept头的请求、406 Not Acceptable错误的成因与修复以及 CSRF 保护对 API 写操作的限制边界。一、探索 Flickr API先学会读懂第三方 REST 接口任何应用与其他应用通信都依赖 API。在动手写自己的 API 之前本课程先安排你读文档、发请求因为每个 API 都不一样阅读文档、弄清对方期望的请求格式是使用 API 的核心技能。关于 API 的基本概念与通用套路可参阅仓库中的 working_with_external_apis.mdAPI key、secret key、版本、OAuth、SDK 等。1.1 如何快速找到 API 文档直接使用搜索引擎检索XYZ API docs往往比在网站里层层导航更快。例如搜索 Flickr API 文档即可定位到其开发者文档页面看到可用的方法methods、请求格式request formats与认证要求。1.2 REST 请求格式端点 查询参数Flickr 提供多种请求格式其中 REST 格式最具代表性。一次典型的 REST 调用结构为端点endpointhttps://www.flickr.com/services/rest/请求数据放在 GET 查询字符串query string或 POST body 中也就是说method要调用的方法名、api_key、业务参数如搜索标签以及响应格式等都以键值对形式随请求一起提交。1.3 无需认证的检索方法flickr.photos.search在 Flickr 众多方法中上传照片、获取联系人列表等大多需要先认证应用或用户账号而flickr.photos.search照片搜索不需要认证只需提供 API key通过在其开发者平台注册即可获得。浏览该方法的文档时可以逐个查看它支持的参数例如tags按标签搜索如puppiesformat响应格式如jsonnojsoncallback是否包裹 JSONP 回调1.4 使用 API Explorer 实战发请求Flickr 文档为flickr.photos.search提供了API Explorer工具它允许你直接使用 Flickr 的官方 API key 执行真实请求用于演示用途。操作步骤在tags参数中输入puppies将响应 Output 下拉框切换为JSON点击 Call Method。页面刷新后底部会返回一大串照片对象photo objects。单个照片对象形如{ id: 11357337313, owner: 84645040N00, secret: 6dd795c9c6, server: 3805, farm: 4, title: Gavin-Feb2013-0127, ispublic: 1, isfriend: 0, isfamily: 0 }更关键的是Explorer 下方会展示它实际发出的请求 URL。将其拆解来看各参数一目了然https://www.flickr.com/services/rest/ ?methodflickr.photos.search api_keybbee7f1e3a3f9cb847b87964d50bf4bc tagspuppies formatjson nojsoncallback1 api_sigd207eb20abbce7c40437a01f759e1388这条 URL 就是前面提到的 REST 端点加上搜索查询与 API key、格式等选项。把它原样粘贴到浏览器地址栏即可看到相同的一批输出。注意其中的api_sig是签名参数它由 API key 派生而来是 Flickr 对请求合法性的一种校验手段。1.5 从元信息到真实图片照片 URL 的拼接规则Flickr 的 API 展示一张照片需要两步先从搜索结果拿到照片的元信息meta information再把这些字段拼装成 Flickr 能识别的图片 URL。官方给出的典型格式为https://live.staticflickr.com/{server-id}/{id}_{secret}_{size-suffix}.jpg把上一步返回的照片字段代入即可拼出可访问的图片地址https://live.staticflickr.com/3805/11357337313_6dd795c9c6.jpg这里server、id、secret分别对应元信息中的server、id、secret字段。省略_{size-suffix}也是合法的默认最长边为 500px。实践小结每个 API 都不同必须通读其文档才能理解基本调用格式。必要时可借助视频教程快速建立整体印象但动手读文档 发请求永远是最可靠的学习路径。二、构建 Kittens API让 Rails 应用同时输出 HTML 与 JSONFlickr 演练只是热身。接下来进入本项目的核心搭建一个 Rails 应用作为数据产出型 API——说直白点就是让所有控制器方法渲染数据而非 HTML。这是对纯 vanilla RESTful 资源的快速操练本项目暂不接入外部 API那将留到下一个项目project_pexels_api.md再做。2.1 为什么 Rails 应用天然就是 API从原理上讲浏览器本身也是一个程序用户请求页面就是在向 Rails 应用发起 API 请求只不过渲染 HTML 负载太常见被默认成了服务端程序的响应类型。当你不想关心页面结构HTML只想直接拿数据时可以对同一 URL 请求 JSON 或 XML 响应——只要控制器配置得当就会得到装满数据的 JSON 数组。关于这一思想的完整阐述见 apis_and_building_your_own.md。2.2 阶段一先让 Kitten 应用在浏览器里正常工作第 1 步初始化项目与模型新建 Rails 应用odin-kittens并初始化 Git 仓库更新 README描述应用用途并链接回本课程项目创建 Kitten 模型包含:name、:age、:cuteness、:softness四个属性。第 2 步搭建路由创建KittensController并为:kittens资源配置全部 7 个 RESTful 动作index / show / new / create / edit / update / destroy。在config/routes.rb中只需一行resources :kittens这一行等价于手动写下 7 条路由是Rails 之道的典型体现。再用rails routes或rails routes --expanded即可查看生成的全部路由。随后把默认路由指向kittens#indexroot to: kittens#index关于resources展开后的 7 条路由、root to:配置与路径助手如edit_kitten_path(3)的详细说明可阅读 routing.md。第 3 步实现控制器动作与视图逐一填充每个控制器动作及其视图输出基础 HTML 页面#index列出所有 Kittens#show展示单个 Kitten#new渲染创建 Kitten 的表单#edit复用同一个表单应抽成 partial供 New 和 Edit 视图共用编辑 Kitten#create与#update各司其职完成数据写入。第 4 步删除链接与 flash 提示在 Show 页、Edit 页以及 Index 页中每个 Kitten 旁边放置delete链接实现flash哈希的展示成功添加/编辑/删除 Kitten 时给出祝贺信息表单出错时给出调侃性的错误提示。flash是 Rails 在请求间传递一次性消息的标准机制配合表单验证使用可显著提升交互体验表单与 flash 的结合用法可参考 form_basics.md。第 5 步自测完整走一遍 Kitten 的增删改查流程确保所有控制器动作运行正常。2.3 阶段二把 Kittens 资源变成 API第 1 步安装 HTTParty 并发送请求HTTParty是一个轻量 HTTP 客户端 gem用来向应用发起请求非常方便。在命令行执行bundle add httparty rails console然后在 Rails 控制台里response HTTParty.get(http://localhost:3000/kittens)查看返回内容response.body # Should return a sloppy mess of HTML. # alternatively, you can do this: response.to_s此时查看服务器输出会看到类似Processing by KittensController#index as */*的日志星号表示接受所有媒体类型all media types——因为没指定格式Rails 默认渲染 HTML。第 2 步请求 JSON 并遭遇 406用headers选项明确要求 JSON 响应json_response HTTParty.get(http://localhost:3000/kittens, headers: { Accept application/json })不出意外你会收到406 Not Acceptable。查看服务器控制台ActionController 会提示控制器发生UnknownFormat错误——原因很简单控制器目前只实现了 HTML 渲染没有声明对 JSON 格式的处理能力。第 3 步用respond_to声明多格式响应修改KittensController的#index方法使用#respond_to来按请求格式返回对应数据def index kittens Kitten.all respond_to do |format| format.html # index.html.erb format.json { render :json kittens } end end#respond_to向块中传入一个 format 对象你只需把对应的渲染调用挂上去不做任何处理时按默认模板渲染 HTML这里是app/views/kittens/index.html.erb请求 JSON 时则把kittens序列化为 JSON 字符串返回。#render很聪明传入:json键时它会自动对该值调用#to_json无需手动转换。此机制的完整示例与讲解见 apis_and_building_your_own.md。第 4 步验证 JSON 输出再次发起带Accept: application/json头的请求确认返回的是合法 JSONjson_response HTTParty.get(http://localhost:3000/kittens, headers: { Accept application/json }) puts json_response.body第 5 步为#show做同样处理用同样的思路改造#show请求时需要带上 Kitten 的 IDHTTParty.get(http://localhost:3000/kittens/1, headers: { Accept application/json })第 6 步理解 CSRF 对 API 写操作的限制本项目不需要为 create / update / destroy 实现 API 版本——因为 Rails 的CSRF 保护会阻止你通过 API 创建、更新或删除 Kittens非浏览器客户端无法携带 CSRF token写请求会被拦截。这既是一个安全特性也提示了一个事实想让外部程序安全地写数据需要额外的认证与令牌机制如 API token相关内容会在后续课程展开。2.4 进阶控制 JSON 输出内容与错误响应原项目到此为止但要让 API 更贴近真实场景以下两个能力值得在同一技能树下掌握均出自 apis_and_building_your_own.md隐藏敏感属性覆写#as_json假设不想把用户的 email 字段随 User 对象一起返回。#to_json内部会先运行#as_json拿到待渲染的属性哈希再用ActiveSupport::json.encode完成序列化。因此只需在模型中覆写#as_json即可精确控制输出字段# app/models/user.rb class User ActiveRecord::Base # Option 1: Purely overriding the #as_json method def as_json(_options{}) { :name self.name } # NOT including the email field end # Option 2: Working with the default #as_json method def as_json(options{}) super({ only: [:name] }.merge(options)) end end控制器照常render :json User.all#render会自动调用#to_json无需手动干预。只返回错误码head :not_found有时只想发送一个无响应体的 HTTP 错误码# app/controllers/users_controller.rb class UsersController ApplicationController def index head :not_found end end2.5 后续项目的延伸API 客户端类与密钥管理本项目的HTTParty.get是控制台里的一次性调用下一个项目 project_pexels_api.md 会把这种调用封装成可复用的客户端类。那里值得提前了解的两个实践要点代码放置位置调用外部 API 的类不一定继承ApplicationRecord可以放在app/models/下或更常见的做法是新建app/services目录存放与外部服务集成的对象密钥管理不要把 API key 硬编码进代码尤其要推送 GitHub 时应改用环境变量、figarogem 或 Rails credentials加密凭证来保存 secret key。三、总结完成本项目后你拥有的是一个既产出 HTML、又通过 JSON 提供数据的 RESTful API 站点既可以用浏览器正常访问也可以用HTTParty、curl 乃至前端 JavaScript 的 AJAX 调用来动态拉取数据甚至可以把它当作移动端 App 的后端。核心要点回顾读懂文档端点、查询参数、认证要求、响应格式是使用任何第三方 API 的第一步Flickr 的 search 演练即是范例respond_to是 Rails 多格式响应的开关同一控制器动作可按请求格式分别渲染 HTML、JSON、XMLAccept头驱动内容协商客户端显式声明期望格式服务端据此选择响应类型未声明处理能力时会收到 406 /UnknownFormatas_json控制输出字段在模型层精确决定 API 暴露哪些属性CSRF 保护天然限制 API 写操作让外部程序安全写数据需要额外的认证令牌机制。进一步延伸阅读仓库中的相关文档apis_and_building_your_own.mdrespond_to、as_json、head错误响应、SOA 架构、working_with_external_apis.mdAPI key、版本、OAuth、SDK、project_pexels_api.mdAPI 客户端类实战与 routing.mdRESTful 路由展开。【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rails RESTful API 构建实战：Kittens API 项目全流程解析（附 Flickr API 调用入门）
Rails RESTful API 构建实战Kittens API 项目全流程解析附 Flickr API 调用入门【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum本篇文章围绕开源课程仓库 cu/curriculum 中 Ruby on Rails 课程的 Kittens API 项目展开带你完成两件事先借助 Flickr 官方文档与 API Explorer 熟悉第三方 RESTful API 的调用套路再亲手搭建一个既能输出 HTML 页面、又能通过 JSON 对外提供数据的 Rails RESTful API。读完本文你将掌握 REST 请求格式、respond_to按格式渲染、HTTParty发起带Accept头的请求、406 Not Acceptable错误的成因与修复以及 CSRF 保护对 API 写操作的限制边界。一、探索 Flickr API先学会读懂第三方 REST 接口任何应用与其他应用通信都依赖 API。在动手写自己的 API 之前本课程先安排你读文档、发请求因为每个 API 都不一样阅读文档、弄清对方期望的请求格式是使用 API 的核心技能。关于 API 的基本概念与通用套路可参阅仓库中的 working_with_external_apis.mdAPI key、secret key、版本、OAuth、SDK 等。1.1 如何快速找到 API 文档直接使用搜索引擎检索XYZ API docs往往比在网站里层层导航更快。例如搜索 Flickr API 文档即可定位到其开发者文档页面看到可用的方法methods、请求格式request formats与认证要求。1.2 REST 请求格式端点 查询参数Flickr 提供多种请求格式其中 REST 格式最具代表性。一次典型的 REST 调用结构为端点endpointhttps://www.flickr.com/services/rest/请求数据放在 GET 查询字符串query string或 POST body 中也就是说method要调用的方法名、api_key、业务参数如搜索标签以及响应格式等都以键值对形式随请求一起提交。1.3 无需认证的检索方法flickr.photos.search在 Flickr 众多方法中上传照片、获取联系人列表等大多需要先认证应用或用户账号而flickr.photos.search照片搜索不需要认证只需提供 API key通过在其开发者平台注册即可获得。浏览该方法的文档时可以逐个查看它支持的参数例如tags按标签搜索如puppiesformat响应格式如jsonnojsoncallback是否包裹 JSONP 回调1.4 使用 API Explorer 实战发请求Flickr 文档为flickr.photos.search提供了API Explorer工具它允许你直接使用 Flickr 的官方 API key 执行真实请求用于演示用途。操作步骤在tags参数中输入puppies将响应 Output 下拉框切换为JSON点击 Call Method。页面刷新后底部会返回一大串照片对象photo objects。单个照片对象形如{ id: 11357337313, owner: 84645040N00, secret: 6dd795c9c6, server: 3805, farm: 4, title: Gavin-Feb2013-0127, ispublic: 1, isfriend: 0, isfamily: 0 }更关键的是Explorer 下方会展示它实际发出的请求 URL。将其拆解来看各参数一目了然https://www.flickr.com/services/rest/ ?methodflickr.photos.search api_keybbee7f1e3a3f9cb847b87964d50bf4bc tagspuppies formatjson nojsoncallback1 api_sigd207eb20abbce7c40437a01f759e1388这条 URL 就是前面提到的 REST 端点加上搜索查询与 API key、格式等选项。把它原样粘贴到浏览器地址栏即可看到相同的一批输出。注意其中的api_sig是签名参数它由 API key 派生而来是 Flickr 对请求合法性的一种校验手段。1.5 从元信息到真实图片照片 URL 的拼接规则Flickr 的 API 展示一张照片需要两步先从搜索结果拿到照片的元信息meta information再把这些字段拼装成 Flickr 能识别的图片 URL。官方给出的典型格式为https://live.staticflickr.com/{server-id}/{id}_{secret}_{size-suffix}.jpg把上一步返回的照片字段代入即可拼出可访问的图片地址https://live.staticflickr.com/3805/11357337313_6dd795c9c6.jpg这里server、id、secret分别对应元信息中的server、id、secret字段。省略_{size-suffix}也是合法的默认最长边为 500px。实践小结每个 API 都不同必须通读其文档才能理解基本调用格式。必要时可借助视频教程快速建立整体印象但动手读文档 发请求永远是最可靠的学习路径。二、构建 Kittens API让 Rails 应用同时输出 HTML 与 JSONFlickr 演练只是热身。接下来进入本项目的核心搭建一个 Rails 应用作为数据产出型 API——说直白点就是让所有控制器方法渲染数据而非 HTML。这是对纯 vanilla RESTful 资源的快速操练本项目暂不接入外部 API那将留到下一个项目project_pexels_api.md再做。2.1 为什么 Rails 应用天然就是 API从原理上讲浏览器本身也是一个程序用户请求页面就是在向 Rails 应用发起 API 请求只不过渲染 HTML 负载太常见被默认成了服务端程序的响应类型。当你不想关心页面结构HTML只想直接拿数据时可以对同一 URL 请求 JSON 或 XML 响应——只要控制器配置得当就会得到装满数据的 JSON 数组。关于这一思想的完整阐述见 apis_and_building_your_own.md。2.2 阶段一先让 Kitten 应用在浏览器里正常工作第 1 步初始化项目与模型新建 Rails 应用odin-kittens并初始化 Git 仓库更新 README描述应用用途并链接回本课程项目创建 Kitten 模型包含:name、:age、:cuteness、:softness四个属性。第 2 步搭建路由创建KittensController并为:kittens资源配置全部 7 个 RESTful 动作index / show / new / create / edit / update / destroy。在config/routes.rb中只需一行resources :kittens这一行等价于手动写下 7 条路由是Rails 之道的典型体现。再用rails routes或rails routes --expanded即可查看生成的全部路由。随后把默认路由指向kittens#indexroot to: kittens#index关于resources展开后的 7 条路由、root to:配置与路径助手如edit_kitten_path(3)的详细说明可阅读 routing.md。第 3 步实现控制器动作与视图逐一填充每个控制器动作及其视图输出基础 HTML 页面#index列出所有 Kittens#show展示单个 Kitten#new渲染创建 Kitten 的表单#edit复用同一个表单应抽成 partial供 New 和 Edit 视图共用编辑 Kitten#create与#update各司其职完成数据写入。第 4 步删除链接与 flash 提示在 Show 页、Edit 页以及 Index 页中每个 Kitten 旁边放置delete链接实现flash哈希的展示成功添加/编辑/删除 Kitten 时给出祝贺信息表单出错时给出调侃性的错误提示。flash是 Rails 在请求间传递一次性消息的标准机制配合表单验证使用可显著提升交互体验表单与 flash 的结合用法可参考 form_basics.md。第 5 步自测完整走一遍 Kitten 的增删改查流程确保所有控制器动作运行正常。2.3 阶段二把 Kittens 资源变成 API第 1 步安装 HTTParty 并发送请求HTTParty是一个轻量 HTTP 客户端 gem用来向应用发起请求非常方便。在命令行执行bundle add httparty rails console然后在 Rails 控制台里response HTTParty.get(http://localhost:3000/kittens)查看返回内容response.body # Should return a sloppy mess of HTML. # alternatively, you can do this: response.to_s此时查看服务器输出会看到类似Processing by KittensController#index as */*的日志星号表示接受所有媒体类型all media types——因为没指定格式Rails 默认渲染 HTML。第 2 步请求 JSON 并遭遇 406用headers选项明确要求 JSON 响应json_response HTTParty.get(http://localhost:3000/kittens, headers: { Accept application/json })不出意外你会收到406 Not Acceptable。查看服务器控制台ActionController 会提示控制器发生UnknownFormat错误——原因很简单控制器目前只实现了 HTML 渲染没有声明对 JSON 格式的处理能力。第 3 步用respond_to声明多格式响应修改KittensController的#index方法使用#respond_to来按请求格式返回对应数据def index kittens Kitten.all respond_to do |format| format.html # index.html.erb format.json { render :json kittens } end end#respond_to向块中传入一个 format 对象你只需把对应的渲染调用挂上去不做任何处理时按默认模板渲染 HTML这里是app/views/kittens/index.html.erb请求 JSON 时则把kittens序列化为 JSON 字符串返回。#render很聪明传入:json键时它会自动对该值调用#to_json无需手动转换。此机制的完整示例与讲解见 apis_and_building_your_own.md。第 4 步验证 JSON 输出再次发起带Accept: application/json头的请求确认返回的是合法 JSONjson_response HTTParty.get(http://localhost:3000/kittens, headers: { Accept application/json }) puts json_response.body第 5 步为#show做同样处理用同样的思路改造#show请求时需要带上 Kitten 的 IDHTTParty.get(http://localhost:3000/kittens/1, headers: { Accept application/json })第 6 步理解 CSRF 对 API 写操作的限制本项目不需要为 create / update / destroy 实现 API 版本——因为 Rails 的CSRF 保护会阻止你通过 API 创建、更新或删除 Kittens非浏览器客户端无法携带 CSRF token写请求会被拦截。这既是一个安全特性也提示了一个事实想让外部程序安全地写数据需要额外的认证与令牌机制如 API token相关内容会在后续课程展开。2.4 进阶控制 JSON 输出内容与错误响应原项目到此为止但要让 API 更贴近真实场景以下两个能力值得在同一技能树下掌握均出自 apis_and_building_your_own.md隐藏敏感属性覆写#as_json假设不想把用户的 email 字段随 User 对象一起返回。#to_json内部会先运行#as_json拿到待渲染的属性哈希再用ActiveSupport::json.encode完成序列化。因此只需在模型中覆写#as_json即可精确控制输出字段# app/models/user.rb class User ActiveRecord::Base # Option 1: Purely overriding the #as_json method def as_json(_options{}) { :name self.name } # NOT including the email field end # Option 2: Working with the default #as_json method def as_json(options{}) super({ only: [:name] }.merge(options)) end end控制器照常render :json User.all#render会自动调用#to_json无需手动干预。只返回错误码head :not_found有时只想发送一个无响应体的 HTTP 错误码# app/controllers/users_controller.rb class UsersController ApplicationController def index head :not_found end end2.5 后续项目的延伸API 客户端类与密钥管理本项目的HTTParty.get是控制台里的一次性调用下一个项目 project_pexels_api.md 会把这种调用封装成可复用的客户端类。那里值得提前了解的两个实践要点代码放置位置调用外部 API 的类不一定继承ApplicationRecord可以放在app/models/下或更常见的做法是新建app/services目录存放与外部服务集成的对象密钥管理不要把 API key 硬编码进代码尤其要推送 GitHub 时应改用环境变量、figarogem 或 Rails credentials加密凭证来保存 secret key。三、总结完成本项目后你拥有的是一个既产出 HTML、又通过 JSON 提供数据的 RESTful API 站点既可以用浏览器正常访问也可以用HTTParty、curl 乃至前端 JavaScript 的 AJAX 调用来动态拉取数据甚至可以把它当作移动端 App 的后端。核心要点回顾读懂文档端点、查询参数、认证要求、响应格式是使用任何第三方 API 的第一步Flickr 的 search 演练即是范例respond_to是 Rails 多格式响应的开关同一控制器动作可按请求格式分别渲染 HTML、JSON、XMLAccept头驱动内容协商客户端显式声明期望格式服务端据此选择响应类型未声明处理能力时会收到 406 /UnknownFormatas_json控制输出字段在模型层精确决定 API 暴露哪些属性CSRF 保护天然限制 API 写操作让外部程序安全写数据需要额外的认证令牌机制。进一步延伸阅读仓库中的相关文档apis_and_building_your_own.mdrespond_to、as_json、head错误响应、SOA 架构、working_with_external_apis.mdAPI key、版本、OAuth、SDK、project_pexels_api.mdAPI 客户端类实战与 routing.mdRESTful 路由展开。【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考