API定义问题

API网关是否支持gzip数据压缩，是否需要添加请求头Accept-Encoding ？

支持的，同时符合以下三点时会将应答压缩：

• 请求中携带Accept-Encoding头，并且这个字段的值必须包含gzip。

• 应答body大小大于2K。

• 应答body contenttype为text/xml text/plain text/css application/javascript application/x-javascript application/rss+xml application/xml application/json application/octet-stream。

用户传了一个未定义的参数，网关将如何处理？

• 入参映射（过滤未知参数）模式下，网关将过滤掉用户多传的参数。

• 入参映射（透传未知参数）模式和入参透传模式下，网关会将参数透传到后端服务。

后端服务是否可以使用HTTPS？

可以，在录入后端服务地址时，请以https://开头，且需要保证您的后端服务已有SSL证书。

API基础定义是什么？

可以配置您API被访问的方式，包含：http或https，以及使用HTTP方法，目前网关支持所有标准的HTTP方法。

为什么要填写API描述？

对于API功能的具体描述，会展示给您的用户。

API类型是什么？

API的类型包含公开、私有两种。若在云市场上架商品，公开的接口会上架展示给客户，私有接口不会展示给客户。

API名称是什么？

名称是API的标识，一个有意义的名称，可以让您的用户能够快速理解API的功能。

API更新是否会有延迟？

不会，API一旦发布会立即生效。

如何使您的API支持HTTPS？

首先，您需要申请一张SSL证书，然后将SSL证书，将证书绑定到网关（查看分组管理—点击分组名称进入分组详情-找到相应域名-上传证书）。

其次，将您的API请求协议修改为：HTTPS或者HTTP和HTTPS。

后端服务地址如何录入？

• 后端服务地址可以是域名，也可以是IP，录入时，要以http://或者https://开头

• 后端服务地址中支持动态参数，用[param]表示。

  • 后端服务地址中可以存在多个动态参数，多个动态参数名称不可重复。

  • 后端服务地址中的动态参数需要配合Path中的动态参数使用，在配置Path时，配置与Path的映射关系。

为什么要定义参数？

参数是API请求的重要组成部分，网关可以根据参数定义为您的用户生成API手册。

参数定义是必须的吗？

不是，但推荐您定义，以便您的API用户能够清楚地理解您的API。

不定义参数网关如何处理？

会根据配置的入参请求模式进行处理。

参数定义包含什么？

描述参数在请求中的位置（path、header、query、body）、参数说明、参数示例及参数值限制。

可以对参数做哪些限制？

网关不仅支持参数最大值、最小值、长度、枚举校验，还支持正则、Json Schema校验。

Path是什么？

Path是您的API调用时展示给客户的固定路径，也是API的标识，在同一分组下HTTP Method+Path不可以重复。

• 在Restful API中，一般表示为资源，格式为资源/子资源，如：instance/disk。

Path中支持动态参数，用[param]表示，如：instance/disk/[diskid]，可以与后端服务地址中的动态参数进行映射。

如何配置Path与后端服务地址中的动态参数？

在配置Path时，控制台可以自动带出后端服务地址中的动态参数，您需要将其与Path中动态参数对应上即可。

Path与后端服务地址中的动态参数名称、顺序是否必须保持一致？

不需要。在配置Path时，可以建立映射关系。

APP是什么，怎么从用户实际的应用关联到我们定义的APP，实际应用是移动端还是Web端？

APP是您在阿里云的一个虚拟应用，是调用API时的身份标识，它可以是您的一个Web应用，也可以是移动端应用，或者其他。API网关会自动给每个APP分配一对APP Key和Secret，用以签名请求，调用API。

如何指定调用环境？

调用API时，默认是调用线上环境的API。

如果要调用测试环境，请在header中增加参数：X-Ca-Stage:TEST。

如果要调用预发环境，请在header中增加参数：X-Ca-Stage:PRE。

如何获取API网关报错信息？

所有的 API 请求只要到达了网关，网关就会返回请求结果信息。

用户需要查看应答的Header部分。其中X-Ca开头的均为网关返回，比较重要信息是：

• X-Ca-Request-Id：请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，以便用于问题排查与跟踪。

• X-Ca-Error-Message：API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端。

• X-Ca-Error-Code：API网关系统错误码，当请求出现错误被网关拦截后，由API网关提供的错误码。

在应答的Header中获得X-Ca-Error-Code与X-Ca-Error-Message可以基本明确报错原因，而X-Ca-Request-Id可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。

X-Ca-Error-Code可以查找错误代码表来获取更详细的排错解释。

如何关闭公网访问？

API网关支持关闭分组的公网访问，仅通过内网访问。操作步骤如下：

1. 登录API网关控制台，在左侧栏单击开放API——分组管理。

2. 在分组列表中找到想要关闭公网访问的分组，单击分组名称进入分组详情页。

3. 在分组详情页的公网二级域名后面找到关闭公网访问按钮，单击确定后即可关闭公网访问。

HTTP/HTTPS请求的返回值为空

HTTP/HTTPS 请求的返回结果有 HttpCode、Header、Body 三部分。当请求报错时，由于没有进入业务逻辑，所以返回的 Body 可能为空，表现为“返回值为空”，但实际上，重要信息都在 Header 里面。

用户发起的 API 请求只要能够到达网关，就会返回成功/错误的结果信息。

重要的返回信息都在Header里面，以X-Ca开头的为网关返回的信息。其中较主要的为下面的几个信息：

X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF 
//请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，可用于问题排查与跟踪
X-Ca-Error-Message: Invalid Url  
//API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}  
//当打开Debug模式后会返回Debug信息，此信息后期可能会有变更，仅用做联调阶段参考

所以如果发送请求后，发现返回值为空，那么看一下返回的 Header 信息。如果请求到达网关就错误返回了，那么 Body 为空很正常，会表现为返回值为空，但是在 Header 里面会有重要信息。

如果Header也为空，那么说明请求没有达到网关，请自行检查网络状况等。

各种语言获取和查看 HTTP/HTTPS 头部信息的方法均可在网上查询到。

HTTPS 证书报错

调用 HTTPS 接口出现证书认证错误或者提示证书已经过期。

后端服务调不通