跳到主要内容

API设计

提示

API设计的主要作用是为了满足研发人员APIfirst的开发习惯，可以预先定义接口请求参数以及响应期望，如果您仅仅需要调试接口，直接进 调试 页面即可，无需在 设计 页面预先定义。

接口基本信息​

在设计tab下可对接口进行开发状态、标签、拓展属性（项目设置中设置) 的定义，已经当对接口需要更加详细，有图标、或表格类的描述时，可在详细说明下的Markdown进行编辑描述

image.png

定义接口请求参数​

可直接可视化定义接口的请求header、query等入参，当项目下的接口都有一个公共的请求参数时，可以使用全局参数的功能快速设置整个项目的公共入参。

设置header入参，支持下拉快速查找常用的header参数名

  1. 支持设置参数的类型
  2. *星号：表示该参数是否必填
  3. 参数值：表示一个入参的示例值
  4. 参数描述：对该参数的一个含义描述（支持快速填充，可了解 参数描述库 功能）

image.png

Query​

设置query入参

  1. 支持设置参数的类型
  2. *星号：表示该参数是否必填
  3. 参数值：表示一个入参的示例值
  4. 参数描述：对该参数的一个含义描述（支持快速填充，可了解 参数描述库 功能）

image.png

Body​

设置body入参：支持多种数据格式 none form-data urlencode（即x-www-form-urlencoded） binary raw（json/xml/javascript/plain/html）

  1. none 格式表示body无请求正文

image.png

  1. form-data 格式支持上传文件以及选择内容类型：当你需要提交有文件的表单时，切换到 form-data

image.png

  1. urlencode（即x-www-form-urlencoded）格式：当你需要提交表单时，切换到 urlencoded

image.png

  1. 当您需要发送JSON对象或者其他对象时，切换到对应的raw类型即可 raw（json/xml）格式，支持数据结构（可以了解数据结构的使用）设计带层级接口的json或xml的入参参数值

image.png

image.png

raw（javascript/plain/html）支持源码编辑方式设计入参的参数值

image.png

Path​

支持RESTful API设计，通过在接口路径中{} 或 : 的方式增加变量，添加后也会在入参中展示出来

image.png image.png

认证​

支持Bearer auth认证、Basic auth认证、Digest auth认证、OAuth 1.0、Hawk authentication、AWS Signature、NTLM Authentication(Beta)、Akamai EdgeGrid八种认证方式。

image.png

定义接口响应期望​

新建期望​

在同一个接口里，由于我们对不同场景下返回的数据结构期望不同，我们可以通过设置多个期望的方式，来满足这个需求。 如图，点击【新建期望】，我们可以选择该期望的状态码、填写期望名称、选择内容格式，点击【确定】新建成功

image.png

设计数据结构​

我们可以选择JSON、XML、 HTML、 Binary四种内容格式，其中JSON/XML格式可以通过可视化的方式设计响应期望返回的数据结构（可以了解数据结构的使用）

image.png

设计响应示例值​

设计好的数据结构也可以mock生成响应示例值

image.png

Mock服务​

提示

在接口还没开发完成时，定义完接口的请求参数和响应期望，可以自动生成 Mock URL，让前端和测试提前进入研发流程。

Apipost提供了智能Mock服务支持填写一些触发条件，并设置当满足/不满足该触发条件后，所启用的期望。开启智能期望后，Apipost会根据已设置的触发条件，匹配旗下的参数判断规则，若满足条件，则会启用预设的期望。具体使用可查看相关文档