Getting Started with APIs

  • Last update: May 19, 2023
  • 1. 概述

    FineDataLink 支持在数据开发中从 API 接口中取数,并解析 JSON 或者 XML 格式的返回结果为二维表结构,然后使用其他数据转换中封装好的可视化算子对数据进行进一步处理和计算。

    本文为你介绍API 接口相关入门知识,便于您后续使用 FDL 进行数据开发。

    2. 接口说明

    2.1 API 中的术语

    • Resource(资源)是指代表某种东西的对象,它具有一些与之相关的数据,并且可以有一组方法对其进行操作。 例如。 学校,班级和学生是资源,删除、添加、更新是要对这些资源执行的操作。

    • Collections(集合)是一组资源,例如,211大学是全国多所优质大学的集合。

    • URL(统一资源定位符)是可以通过其定位资源的路径,并且可以对其执行某些操作。

    URL应仅包含资源(名词)而不包含动作或者动词。但是对于例子:增加学生的API路径:/addNewStudent,包含操作addNew以及资源名称Student,因此这个路径并不标准

    正确的方法是/schools ,这是一个很好的例子,不包含任何动作。

    但是我们怎么告诉服务器,有关学校资源的操作呢,例如增加,删除或者更新学校?

    这就需要使用 HTTP 方法 (GET,POST,DELETE,PUT) 。

    例如:

    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 方法也能满足需求。

    请求参数

    用来传递信息的变量。即需要请求的字段名的名称和规则:都是哪些字段,字段的类型是什么,是否必填字段等等

    • URL传参

    • Headers 请求头

    • Body 请求内容

    详情参见本文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 中输入请求头和请求参数使用接口,如下图所示:

    附件列表


    主题: 数据开发
    Previous
    Next
    • Helpful
    • Not helpful
    • Only read

    滑鼠選中內容,快速回饋問題

    滑鼠選中存在疑惑的內容,即可快速回饋問題,我們將會跟進處理。

    不再提示

    10s後關閉

    Get
    Help
    Online Support
    Professional technical support is provided to quickly help you solve problems.
    Online support is available from 9:00-12:00 and 13:30-17:30 on weekdays.
    Page Feedback
    You can provide suggestions and feedback for the current web page.
    Pre-Sales Consultation
    Business Consultation
    Business: international@fanruan.com
    Support: support@fanruan.com
    Page Feedback
    *Problem Type
    Cannot be empty
    Problem Description
    0/1000
    Cannot be empty

    Submitted successfully

    Network busy