我要投搞

标签云

收藏小站

爱尚经典语录、名言、句子、散文、日志、唯美图片

当前位置:天空彩票 > 端点编码 >

API设计:先思考再编码

归档日期:06-13       文本归类:端点编码      文章编辑:爱尚语录

  API是定义应用程序接口的通用术语,换句话说,定义了用户(人或机器)如何与程序交互。在Web开发世界中,API通常是响应客户端结构化文本数据请求的网站端点集合。

  Web开发人员广泛使用和讨论的另一个概念是RESTFul Web API。它由Roy Fielding定义为一种架构风格,在客户端和服务器之间提供良好的通信协议。它包含了一些约束:无状态通信,基础技术(通常为HTTP)的使用和超媒体作为应用程序状态的引擎的使用。换句话说,它提出了一些用于构建web API的模式。为了简单起见,在这篇文章中将Web API简称为API。

  这段JSON的数据是智能手机从Facebook API响应中收集的Facebook状态消息的示例。很漂亮,对不对?

  现在想象你是Facebook的工程师,负责这个API。有天您突然决定将id字段名称更改为message_id。嗯,这个小的变化可能破坏Facebook。真的。依赖于先前定义的结构的所有设备现在都无法收集这个JSON响应,也就无法向用户显示任何内容。

  3.难学:消费使用数据和开发API会是一段陡峭的学习曲线.性能问题:抛出未进行规划设计的API代码通常会长期产生性能瓶颈。

  API是您的应用程序与其用户之间的合同。它不能突然改变,否则会导致那些已经调用它的客户端发生混乱,API不应该在没有预见性的情况下仓促建立。这就是需要设计的地方:创建一个规划或约定,用于构建对象,系统或可衡量的人类互动。

  在介绍API代码之前,让我们先看一下超文本传输​​协议HTTP,顾名思义,它是用于在网络上传输数据。它有一组关于客户端和服务器如何交换信息的规则。其主要组成部分有:

  URL:您的资源在Web上的位置,您的端点的地址。一个示例是使用列出您的用户。

  请求方法:客户端希望在特定端点上执行的操作。GET 用于检索资源,POST创建一个,PUT 和PATCH 来更新现有的资源,DELETE删除东西。

  头部Header:包含有关客户端或服务器的信息。例如:内容类型(格式)、方法、认证令牌和其他。

  正文内容body:客户端与服务器之间发送和接收的数据。JSON是事实上的标准。

  状态代码:一个三位数字,用于告知请求状态。总而言之,2xx 状态表示成功,4xx意味着客户端错误,5xx意味着服务错误。

  在设计API时,有一些规范可以帮助您。最常用的是使用纯JSON的Swagger、使用YAML表示法的RAML和支持markdown语法的API蓝图Blueprint。我喜欢上了后者:即使它是邻居新的酷孩子,它已经成熟足够和能够让人愉快的工作。这里会阐述为什么。

  API蓝图(支持markdown语法)是简单的,并且可以在API生命周期的访问每个元素。它的语法简洁而富有表现力。使用API​​ 蓝图,您可以快速设计和创建API,或记录和测试已部署的任务关键型API。

  它是一个开放源代码,专注于协作,易于学习和良好记录的规范,由Apiary创建,其核心是设计第一,周围有一些很棒的工具:从模拟服务器生成器到全功能生命周期解决方案。

  除了蓝图,还有MSON(Markdown语法对象符号),它以人类可读的方式定义数据结构,不是手动编写端点的主体数据,而是在可重用对象中表示它们。

  除此之外,蜜蜂是一个协作平台,用于创建、呈现、测试和服务您的API。他们有一个免费的公共项目计划,你可以直接用你的GitHub帐户注册,以创建自己的设计。

  如果您访问上面这个项目,您将看到一个漂亮的页面。真棒是:自动为每个项目创建模拟服务器是 - 见这里,看到魔法吗?不需要代码它也工作。任何有HTTP和Blueprint基本知识的人都可以创建一个模拟API,并从客户那里获得反馈。

  上面的例子很简单,可以通过get获得。您可以查看蓝图教程和文档以深入了解其语法,并在此处阅读规范。此外,这是一个开源项目 - 欢迎社区的任何贡献。

  恭喜!现在你掌握了设计API所需的知识。但在你开始启动你的系统之前,这里有一些小提示:

  我们的/cakes/端点可能有创建,读取,更新,删除和列表操作。你可以使用HTTP动词和URL来构造这些动作,例如:

  GET是获得,POST是发布。如果你只是想要一个蛋糕的列表不要使用POST。

  你不需要在URL中指定操作,我们已经知道POST创建一些东西,所以createCake不需要包含create字眼。

  更清晰的URL,也会告诉我们可能其他方法将按这种方式使用,如GET /cakes。

  GET /cakes应该返回一个蛋糕列表,所以GET /cake/1应该返回第一个蛋糕,对吧?很不幸的是,不行。即使它在我们的语言是有道理的,它只会用更多端点搞乱客户端和开发人员。

  每个人都憎恨HTTP响应状态代码是2xx,却返回一个错误的消息!使用正确的代码:

  当发生问题失败时,通知客户端发生了什么以及如何恢复。这里有一个很好的方法:

  API端点将使用资源表示进行响应。将这些资源当作对象类,然后在现实世界中代表事物。

  相信我,使用设计第一的哲学将带给你更好的睡眠。这里有一些好的API优点:

  与您的客户交谈:了解他们需要什么,而不是他们想要什么。没有客户端的API只是一个坏的API。

  在实现它之前使用你的API:创建一个模拟服务器来获得最终结果并演示。如果可以,与您未来的客户谈话并询问他们的意见。

本文链接:http://diverlandya.com/duandianbianma/570.html