目录:
1. 概述编辑
FineDataLink 支持在数据开发中从 API 接口中取数,并解析 JSON 或者 XML 格式的返回结果为二维表结构,然后使用其他数据转换中封装好的可视化算子对数据进行进一步处理和计算。
本文为你介绍API 接口相关入门知识,便于您后续使用 FDL 进行数据开发。
2. 接口说明编辑
2.1 API 中的术语
Resource(资源)是指代表某种东西的对象,它具有一些与之相关的数据,并且可以有一组方法对其进行操作。 例如。 学校,班级和学生是资源,删除、添加、更新是要对这些资源执行的操作。
Collections(集合)是一组资源,例如,211大学是全国211所优质大学的集合。
URL(统一资源定位符)是可以通过其定位资源的路径,并且可以对其执行某些操作。
URL应仅包含资源(名词)而不包含动作或者动词。但是对于例子:增加学生的API路径:/addNewStudent,包含操作addNew以及资源名称Student,因此这个路径并不标准。
正确的方法是/schools ,这是一个很好的例子,不包含任何动作。
但是我们怎么告诉服务器,有关学校资源的操作呢,例如增加,删除或者更新学校?
这就是HTTP方法 (GET,POST,DELETE,PUT) 。
API接口的资源应始终为复数,如果我们要访问资源的一个实例,我们可以在URL中传递id或者name之类的。
例如:
HTTP方法 | 路径 | 含义 |
---|---|---|
GET | /schools | 获取所有的学校 |
GET | /schools/清华 | 获取名字叫清华大学的详细信息 |
DELETE | /schools/清华 | 从学校列表中,删除清华大学 |
如果资源和资源之间可能有父子关系,那又应该如何设计呢?例如学校的学生,下面是一些示例:
HTTP方法 | 路径 | 含义 |
---|---|---|
GET | /schools/清华/students | 获取清华大学的所有学生 |
GET | /schools/清华/students/张三 | 获取清华大学名字叫张三的学生的详细信息 |
DELETE | /schools/清华/students/张三 | 删除清华大学名字叫张三的学生 |
2.2 HTTP 请求方法
HTTP方法 | 说明 | 示例 |
---|---|---|
GET | 从资源请求数据,不应产生任何其他作用。 | /schools/清华/students,返回所有清华大学的学生 |
POST | 请求服务器在数据库中创建资源,主要是在提交Web表单时。 POST是非幂等的,这意味着多个请求将具有不同的效果。 | /schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。 |
PUT | 请求服务器更新资源或创建资源(如果不存在) PUT是幂等的,这意味着多个请求将具有相同的效果。 | /schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。 |
DELETE | 请求从数据库中删除资源或其实例。 | /schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。 |
3. 如何看接口文档编辑
API接口文档一般分为接口描述、接口地址、请求方法、请求参数、响应内容、错误代码、实例几个部分:
内容 | 说明 |
---|---|
接口描述 | 简单描述接口的逻辑和作用。例如说明这是一个发送消息的接口、查询天气的接口 |
接口地址 | 这个地址表示的是网络地址,即url,我们需要调用接口url,获取响应内容 |
请求方法 | 常见的请求方法为 GET 和 POST,注:FDL 支持GET和POST两种请求方式,若您需要使用PUT或者 DELETE 请求方法,POST 方法也能满足需求。 |
请求参数 | 用来传递信息的变量。即需要请求的字段名的名称和规则:都是哪些字段,字段的类型是什么,是否必填字段等等
详情参见本文3.1、3.2 节。 |
响应内容 | 接口返回的字段名称和规则 |
错误代码 | 对接口的错误用代码进行归类,以便能快速找到错误原因,解决问题 |
实例 | 实际调用时的响应的内容 |
3.1 GET请求
GET通常用于获取服务端数据:
GET方式在url后面拼接参数,只能以文本的形式传递参数;
传递的数据量小,4kb左右(不同浏览器会有差异);
安全性低,会将信息显示在地址栏;
速度快,通常用于对安全性要求不高的请求;
GET请求也可以有Headers参数
GET请求可以传递参数,一般的传递方式为 URL传参,例如:
在GET请求中,遇到参数 / Params / Querys 均是以 URL传参的形式进行传递。
在POSTMAN中,可以直接用 URL传参形式,也可以在Params处填写KEY和VALUE,会自动进行拼接(演示)。
在 FDL 中也可以通过直接URL传参或者请求参数写值自动拼接使用接口,如下图所示:
3.2 POST请求
post提交数据相对于get的安全性高一些。
传递数据量大,请求对数据长度没有要求;
用于密码等安全性要求高的场合,提交数据量较大的场合,如上传文件,发布文章等。
POST请求一般由Url 、 Headers 、 Body组成,如果在POST请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用URL参数传递参数,而POST请求的接口文档里面的参数一般指Body。
3.2.1 使用URL传参的接口
3.2.2 使用Body传参的接口
POST请求不同的请求格式:
类型 | 说明 |
---|---|
application/json,JSON数据格式,一般使用raw-JSON | 最常见的格式,例如 {"name":"Roxy","password":"123"} 此时的请求头为: |
text/plain,纯文本格式,一般使用raw-Text | 例如:name:ziv,password:123 |
text/xml(了解),XML数据格式,一般使用raw-XML | 例如: <?xml version="1.0" encoding="UTF-8" ?> <name>ziv</name><password>123</password> |
multipart/form-data | 它会将表单的数据处理为一条消息,以标签为单元,用分隔符分开。由于有boundary隔离,所以multipart/form-data既可以上传文件,也可以上传键值对,它采用了键值对的方式,所以可以上传多个文件 |
application/x-www-from-urlencoded | 会将表单内的数据转换为键值对,&分隔。 |
在 FDL 中输入请求头和请求参数使用接口,如下图所示: