API 如何创建?-问答-阿里云开发者社区-阿里云

开发者社区> 轩墨> 正文

API 如何创建?

2017-10-26 11:46:37 1972 0

创建 API 即录入 API 的定义,支持“入参映射”和“入参透传”两种请求模式。

创建API


创建 API 需要录入 API 的基本信息、服务信息、请求信息、返回信息。
此外,网关支持您配置常量参数、系统参数,这些参数对您的用户不可见,但是网关可以在中转时将常量参数、系统参数加入请求中,传递至后端服务,满足您后端的一些业务需求。比如您需要网关每次向您发送请求都带有一个 keyword[backcolor=transparent]aligateway,您就可以把 [backcolor=transparent]aligateway 配置为常量参数,并指定接收的位置。

第一部分:定义请求的基本信息


[backcolor=transparent]API 基本信息包括 API 分组、 API 名称、安全认证方式、 API 类型、描述。
  • API 创建时需要选择分组。分组是 API 的管理单元,创建 API 之前您需要先创建分组( API 分组的详细说明见 API 开放),选择分组即选择 [backcolor=transparent]Region。
  • API 名称:API名称标识,需要手工录入。

  • 安全认证方式:是 API 请求的认证方式,目前支持 [backcolor=transparent]阿里云APP、[backcolor=transparent]OpenID Connect 和 [backcolor=transparent]无认证 三种认证方式。
    1. [backcolor=transparent]阿里云APP:认证方式即要求请求者调用该 API 时能够通过对APP的身份认证。
    2. [backcolor=transparent]OpenID Connect:是一套基于 OAuth 2.0 协议的轻量级规范,提供通过RESTful APIs 进行身份交互的框架。可以使用OpenID Connect和您的自有账号系统无缝对接,详细介绍请参照 OpenID Connect
    3. [backcolor=transparent]无认证:认证方式即任何人知晓该 API 的请求定义后,均可发起请求,网关不对其做身份验证,均会转发至您后端服务。(强烈不建议使用此模式)

  • API 类型分为公开和私有两种。
    1.[backcolor=transparent]私有 类型的 API ,当所在分组上架云市场时,默认不包括该类型的 API 。如果有用户想要调用您的 API ,您需要主动操作授权,否则用户无渠道获取 API 信息。2.[backcolor=transparent]公开 类型的 API ,所有用户均有机会在 发现 API 页面看到 API 的部分信息。[backcolor=transparent]公开 类型的 API 都会跟 API 分组上架到云市场,供用户购买和调用。
  • 描述: API 功能描述,会生成在 API 文档中。


第二部分:定义 API 请求


这部分是定义用户如何请求您的 API ,包括协议、Method、Path、入参的定义。
  • 协议。 API 调用支持 HTTP/HTTPS 协议。

  • Method。支持标准的 HTTP Method,可选择 PUT、GET、POST、DELETE、HEAD。

  • [backcolor=transparent]Path。Path 指相对于服务 host, API 的请求路径。请求 Path 可以与后端服务实际 Path 不同,您可以随意撰写合法的有明确语义的 Path 给用户使用。您可以在请求 Path 中配置动态参数,即要求用户在 Path 中传入参数,同时您的后端又可以不在 Path 中接收,可以映射为在 Query、Header 等位置接收。在 开放 API 接入 API 网关 中,有详细的举例说明,更有清晰的截图展示。
  • [backcolor=transparent]入参请求模式。网关对入参的处理模式,支持“入参映射”和“入参透传”两种模式。
    1. [backcolor=transparent]入参映射:既 API 网关在接收到您的 API 请求时,通过映射关系将请求转换成您后端需要的格式。使用入参映射模式:定义方式:此类API需要在定义时添加前后端参数映射关系。
    2. 使用场景同一接口,在 API 网关定义不同的API,以服务差异化的用户;
    3. 通过 API 网关规范化陈旧系统接口。
  • 实现功能
    • 支持您配置前端和后端的全映射,即参数混排。可以让 API 的消费者在 [backcolor=transparent]Query 传入参数, 后端从 [backcolor=transparent]Header 里接收等。参数名称转换
    • 参数位置转换
  • 可以定义参数的校验规则,实现请求参数的预校验,降低后端处理非法请求的压力。
    • 参数长度校验
    • 参数数值大小校验
    • 参数正则校验
    • 参数Json Schame校验
  • 入参透传:即 API 网关在接收到 API 请求后,不对请求进行处理,直接转发到后端服务。此模式下:
    1. 无法实现参数校验
    2. 无法生成详细的 API 调用文档
    3. 自动生成的SDK不包含请求入参
[backcolor=transparent]入参。定义您 API 的请求入参,包含参数名、参数位置、类型、是否必填、默认值、示例、描述等信息。[backcolor=transparent]入参透传模式下不需要录入参数。
  • 参数名。展示给用户的参数名称。
  • 参数位置。参数在请求中的位置,包含Head、Query、Body、Path(Parameter Path),当您在 Path 中配置了动态参数,存在参数位置为Parameter Path的同名参数。
  • 类型。字段的类型,支持:String、Int、Long、Float、Double、Boolean。
  • 是否必填。指此参数是否为必填指,当选择为是时,网关会校验用户的请求中是否包含了此参数,若不存在则拒绝用户请求。
  • 默认值。当“是否必填”为否时生效,在用户请求中不包含此参数时,网关自动添加默认值给后端服务。若用户传递,则按用户请求传递给后端服务。
  • 示例。指参数的填写示例,生成 API 文档、上架 API 市场时的参数示例。
  • 描述。参数的用途描述及使用的注意事项,生成API文档、上架API市场时的参数描述。
  • [backcolor=transparent]参数校验规则。每个入参后可点击 [backcolor=transparent]编辑更多 配置校验规则。如参数值的长度、取值大小、枚举、正则、Json Shcame等等。网关会参照校验规则对请求做初步校验,如果入参不合法,则不会到达您的后端服务,大大的降低了后端服务的压力。


第三部分:定义后端服务信息


这部分主要是定义一些参数的前后端映射,具体描述的是您后端真实服务的 API 配置。用户请求到达网关后,网关会根据您的后端配置映射为对应实际后端服务的请求形式,去请求您的后端。包括后端服务地址、后端Path、后端超时时间、参数映射、常量参数、系统参数。
  • 后端服务类型。目前支持HTTP/HTTPS、FunctionCompute两种。HTTP/HTTPS。若您的服务为HTTP/HTTPS服务,则选择此项。注意若您是HTTPS服务,后端服务必须有SSL证书。
  • FunctionCompute。为阿里云函数计算,使用方法请参照:以函数计算作为 API 网关后端服务
VPC 通道。当您的后端服务在 VPC 中时,需要使用此通道,使用方法: 专属网络 VPC 环境开放 API后端服务地址。后端服务的 host,可以是一个域名,也可以是 http(s)://host:port 的形式。填写时,必须填写 http://、https://后端 Path。Path 是您的 API 服务在您后端服务器上的请求路径,实际请求路径。若您后端 Path 需要接收动态参数,那么需要声明该参数是调用者从哪个位置哪个参数传入的,即声明映射关系。后端超时时间。指 API 请求到达网关后,网关去调 API 后端服务的响应时间。由网关请求后端开始到网关收到后端返回结果。该值不能超过30秒。超过该值网关会放弃请求后端服务,并给用户返回相应的错误信息。参数映射。网关支持参数在前端、后端的全映射,包括名称映射和位置映射。位置映射包括 Path、Header、Query、Body 的混排映射。也就是说,您可以将您的后端服务通过映射完成包装成更规范、更专业的 API 形态。这部分就是在声明前后端 API 映射关系的。在 开放 API 接入 API 网关 中,有详细的举例说明,更有清晰的截图展示。[backcolor=transparent]注意前后端参数名称不能重复。常量参数。比如您需要网关每次请求您后端时都带有标记 [backcolor=transparent]apigateway,那么您可以直接将标记配置为常量参数。常量参数对您的用户不可见,请求达到网关后,网关会自动在指定位置加上该参数再去请求您的后端。
系统参数。指 API 网关的系统参数,这些参数默认不会传递给您,但是如果您需要获取,您可以在 API 里配置接收位置和名称。具体内容如下表:
参数名称参数含义
CaClientIp发送请求的客户端IP
CaDomain发送请求的域名
CaRequestHandleTime请求时间(格林威治时间)
CaAppId请求的APP的ID
CaRequestIdRequestId
CaApiNameAPI 名称
CaHttpSchema用户调用 API 使用的协议,http或者https
CaProxy代理(AliCloudApiGateway)

[backcolor=transparent]注意:您所有录入的参数,包括 Path 中的动态参数、Headers 参数、Query 参数、Body 参数(非二进制)、常量参数、系统参数,参数名称保证全局唯一。即如果您同时在 Headers 和 Query 里各有一个名为 [backcolor=transparent]name 的参数,是不允许的。

第四部分 定义返回结果


您需要录入返回ContentType、返回结果示例、失败返回结果示例和错误码定义,将会生成 API 文档和在 API 市场的展示。

API调试


API 定义录入完成后,您可以在API调试页面调试API,以确定 API 的可用性。

发布


完成以上定义后,您就完成了 API 的创建。下一步您可以测试、发布、开放 API 服务到市场,还可以为 API 绑定 签名密钥流量控制等安全配置。
取消 提交回答
全部回答(0)
相关问答

4

回答

Spark 【问答合集】

社区小助手 2019-05-29 14:13:40 123653浏览量 回答数 4

31

回答

[@倚贤][¥20]刚学完html/css/js的新手学习servlet、jsp需要注意哪些问题?

弗洛伊德6 2018-10-27 21:52:43 145588浏览量 回答数 31

33

回答

Win Server 2003-2016 加密勒索事件必打补丁合集

妙正灰 2017-05-15 10:44:38 277466浏览量 回答数 33

42

回答

【精品问答集锦】Python热门问题

小六码奴 2019-05-30 15:27:34 135468浏览量 回答数 42

38

回答

安全组详解,新手必看教程

我的中国 2017-11-30 15:23:46 256837浏览量 回答数 38

294

回答

Linux Bash严重漏洞修复紧急通知(已全部给出最终修复方案)

qilu 2014-09-25 13:26:50 431582浏览量 回答数 294

82

回答

OSS入门教程

belle.zhoux 2014-07-07 17:14:27 149296浏览量 回答数 82

249

回答

阿里云LNAMP(Linux + Nginx + Apache + MySQL + PHP)环境一键安装脚本

云代维 2014-02-14 15:26:06 302566浏览量 回答数 249

24

回答

【精品问答】python技术1000问(1)

问问小秘 2019-11-15 13:25:00 471220浏览量 回答数 24

13

回答

游戏云精彩帖汇总

nono20011908 2014-08-22 11:00:12 203614浏览量 回答数 13
+关注
2351
文章
701
问答
推荐问答
相关电子书
更多
文娱运维技术
立即下载
《SaaS模式云原生数据仓库应用场景实践》
立即下载
《看见新力量:二》电子书
立即下载