文档

创建REST API并添加接口

更新时间:

REST API主要面向以业务为中心的开发团队,适用于API First、API精细化管理等场景,支持通过控制台、AI大模型或者基于OpenAPI 导入的方式创建。本文主要介绍如何创建REST API并添加接口。

概述

API是一个整体的服务定义,定义了如何与系统进行交互的规则和方法,包含一系列接口;通过API,您可以调用预定义的功能、访问数据资源或触发系统行为,而无需了解底层实现的复杂细节。而接口是API的具体实现部分,提供了访问和操作API功能的入口点,每个接口通常对应一个特定的功能或服务。通过接口,客户端应用可以与服务器进行交互,执行所需的操作并获取响应结果。

通过控制台创建并添加接口

创建API

  1. 登录云原生API网关控制台

  2. 在左侧导航栏,单击API管理,并在顶部菜单栏选择地域。

  3. 在API管理页面,单击创建API,单击REST API卡片中的创建

  4. 创建HTTP API面板中,根据页面提示配置API相关参数。

    配置项

    说明

    API名称

    自定义创建的API名称。

    重要

    API名称必须全局唯一。

    协议

    支持HTTPHTTPS

    Base Path

    API的基本路径,访问具体接口时,完整路径为http(s)://{域名}/{apiBasePath}/{接口Path}

    版本管理

    是否启用API版本管理能力,不同版本的API视为独立的API,它们具有相同的API名称,但API的其他基本信息和接口信息可以不同。访问时需要指定版本标识符。

    开启版本管理功能后,需要配置版本号使用方式

    说明
    • 选择使用方式Query时,需要配置参数项添加Query

    • 选择使用方式Header时,需要配置参数项添加Header

    版本号

    相同API名称下,以版本号进行区分。

    使用方式

    支持PathQueryHeader三种方式。

    • 使用Path时,需要完整访问路径为:/API基本路径/版本号/接口路径。

    • 使用Query时,完整访问路径为:/API基本路径/接口路径,请求参数中需要配置参数项添加Query为版本号。

    • 使用Header时,完整访问路径为:/API基本路径/接口路径,请求头中需要配置参数项添加Header为版本号。

    描述

    填写API的相关描述。

添加API接口

  1. 登录云原生API网关控制台

  2. 在左侧导航栏,单击API管理,并在顶部菜单栏选择地域。

  3. 在API列表中单击目标API,在API详情页,添加接口:

    • 如果目标API开启了版本管理,需要先选择版本,后单击添加接口

      image

    • 如果目标API未开启版本管理,单击添加接口

  4. 创建接口面板中,配置接口相关参数,并单击创建

    配置项

    说明

    接口名称

    自定义创建的接口名称,在API下需要全局唯一。

    接口Path

    接口的具体路径。

    Method

    接口的请求方法。接口的路径+接口的方法,需要在API下全局唯一。

    描述

    接口的描述信息。

    请求定义

    支持定义HeaderQueryParameter Path参数以及Body参数。

    其中Path参数支持在接口Path中三种定义变量的方式:

    • /books/{bookId}

    • /books/[bookId]

    • /books/:bookId

    其中,推荐使用{bookId}方式进行定义。

    请求定义仅用于生成SDK和文档,不对运行时进行校验。

    响应定义

    定义不同响应码的数据结构。

    响应码定义仅用于生成SDK和文档,不对运行时进行校验。

    Mock

    Mock配置仅在API发布Mock场景下生效。

通过AI大模型创建并添加接口

  1. 登录云原生API网关控制台

  2. 在左侧导航栏,选择API管理,并在顶部菜单栏选择地域。

  3. 在API管理页面,单击创建API,选择REST API卡片中的AI大模型创建

  4. 基于AI大模型创建面板中,根据页面提示配置相关参数,单击生成Swagger示例,在左侧自动生成API及接口。

    配置项

    说明

    API名称

    自定义创建的API名称。

    重要

    API名称必须全局唯一。

    场景

    描述API的使用场景,是关于什么的服务。

    资源及对应操作

    数据对象,最多创建5个数据对象

    名称

    数据对象的名称,如图书。

    属性

    数据对象的属性,如书名、作者,可直接粘贴数据模型相关的定义文本或代码。

    操作:增/删/改/查

    • 增:新增资源接口描述,如根据ID、名称新增。

    • 删:删除资源接口描述,如根据ID删除资源。

    • 改:修改资源接口描述,如根据ID,修改资源名称。

    • 查:查看资源接口描述,如根据ID查询资源信息

    其他

    填写其他补充内容。

通过导入OpenAPI文件创建并添加接口

  1. 登录云原生API网关控制台

  2. 在左侧导航栏,选择API管理,并在顶部菜单栏选择地域。

  3. 在API管理页面,单击创建API,单击REST API卡片中的导入

  4. 基于OpenAPI创建文件面板中,配置API相关参数,并单击预检并创建

    配置项

    说明

    API名称

    自定义创建的API名称,API名称需要全局唯一。

    OpenAPI文件

    支持选择文件或粘贴文本内容。

    版本管理

    是否启用API版本管理能力,不同版本的API视为独立的API,它们具有相同的API名称,但API的其他基本信息和接口信息可以不同。访问时需要指定版本标识符。

    开启版本管理功能后,需要配置版本号使用方式

    说明
    • 选择使用方式Query时,需要配置参数项添加Query

    • 选择使用方式Header时,需要配置参数项添加Header

    版本号

    相同API名称下,以版本号进行区分。

    使用方式

    支持PathQueryHeader三种方式。

    • 使用Path时,需要完整访问路径为:/API基本路径/版本号/接口路径。

    • 使用Query时,完整访问路径为:/API基本路径/接口路径,请求参数中需要配置参数项添加Query为版本号。

    • 使用Header时,完整访问路径为:/API基本路径/接口路径,请求头中需要配置参数项添加Header为版本号。

    描述

    填写API的相关描述。