服务产线－创建API

更新时间：2018-03-27 11:26:18

概述

API是服务的载体，服务有多个版本，每个版本包含一组API。您可以将已经存在的RESTful API接入进来，也可以基于平台提供的能力开发出一个托管的RESTful API。

创建API

创建了版本之后，您就可以在该版本上创建API，所以点击下图中的“API管理”入口进入。

undefined

上图中点击某个版本的“API管理”，就进入下面的API管理页面，这个页面中会列出当前版本的所有API列表，您可以对相应的API进行操作。

  • 如果这是您的第一个版本，或者你之前的服务没有已经上线的版本，那么当前版本的API列表则为空

  • 如果您的服务之前有上线的版本，那么当前版本会自动继承最新上线版本的所有API。

undefined

点击新增API按钮进入创建API的流程。 备注：我们这里新增的API都是http/https协议访问的web API

填写API基本信息

这是新增API的第一个步骤，填写完API名称和API简介后点击下一步

  • 当前版本：自动继承当前服务的版本

  • API名称：支持英文和数字，大小写敏感

  • API简介：对API的功能进行简要描述，会出现在API文档中，便于别人了解您的API功能

undefined

定义API请求

这是新增API的第二个步骤，完成的是第三方使用者或是您自己在调用这个API的时候的请求样式和入参，样式包括：请求协议、域名、Path、HTTP Method等内容。

请求基础定义

undefined

  • 协议

在定义API请求时中可以同时支持 HTTP/HTTPS 协议，后端服务如果要支持 HTTPS，需要绑定独立
域名并匹配 SSL 证书

  • API访问域名（默认）

系统为您默认生成的二级域名，便于您调试API，该域名只支持HTTP方式访问，如果您要用HTTPS访问API，请添加自己的自定义域名

  • API访问域名（自定义）

您在服务管理页面上的域名信息Tab页添加的自定义域名，发布到云市场的服务必须绑定自定义域名

  • HTTP Method

POST（默认值：当前API的调用的HTTP Method只支持POST方式，在调用API的时候请注意）

  • 请求Path

请求API的URL中域名之后，参数之前的部分，比如您的API的请求地址是：http://rlsxsb.market.alicloudapi.com/face/attribute，那么Path即/face/attribute。

  • 入参请求模式

当前只支持参数透传，就是这里定义的入参会直接传给您即将在第三步定义的后端服务，作为后端服务的入参

入参定义

入参定义是指您调用API时需要传入的参数说明，包括参数名、参数类型、是否必填、默认值、描述、示例等。

  • 顺序：参数在请求中的位置

  • 参数名：展示给用户的参数名称

  • 类型：字段的类型，支持：String、Int、Long、Float、Double、Boolean

  • 是否必填：指此参数是否为必填指，当选择为是时，平台会校验用户的请求中是否包含了此参数，若不存在则拒绝用户请求

  • 默认值：当“是否必填”为否时生效，在用户请求中不包含此参数时，平台自动添加默认值给后端服务。若用户传递，则按用户请求传递给后端服务

  • 示例：指参数的填写示例，生成 API 文档、上架云市场时的参数示例

  • 描述：参数的用途描述及使用的注意事项，生成API文档、上架云市场时的参数描述

undefined

备注：这里定义的入参，外部请求该API的时候，需要把参数放到body里面传入才可以进行调用，因为目前只支持POST方式调用API

定义API后端服务

上一步我们完成的是API的定义，这一步我们需要给出这个API的实现，也就是API后端服务，这个后端服务分为托管和非托管两种。

  • 非托管
    您已经有一个RESTful API，现在想无缝集成到Link Develop上的移动应用（插件）、Web应用（插件）中，或者想上架到云市场实现变现，那么在这里配置下您已有的这个RESTful API的请求样式，方便我在平台中进行调用。

  • 托管
    利用Link Develop提供的流式编辑器，您可以通过可视化的方式编排出一个serveless的API后端服务，由平台提供API后端服务的执行容器。API完全运行在平台上，您不需要自己去搭建服务器。

非托管

选择非托管API后端服务，您就只需要完成您已有的RESTful API的请求样式就好了，入参不需要定义（因为我们是参数透传的方式，第二步定义的API请求的入参会直接透传给您在这里配置的RESTful API），请求样式包括：

  • 协议

HTTP或HTTPS（如果选择 HTTPS,请您完成自定义域名的配置，并填写好SSL证书内容等信息）

  • 后端请求地址
    您的RESTful API的请求地址，包含协议头、域名、Path等

  • 后端超时定义

默认3000ms，目前不可选，您的API如果超过这个时间还没有返回则会报超时错误

  • HTTP Method
    支持POST和GET两种

undefined

托管

托管方式是利用Link Develop提供的流式编辑器上进行API后端服务的开发，不需要请求您已经存在的RESTful API，直接点击“新增流式服务编排”进入开发即可，具体开发的操作放在下一章节进行说明，开发完成之后需要将新增API流程走完才算完成对API的定义。

undefined

定义返回结果及错误码

这里定义的返回结果和错误码只是为了最后自动形成的API文档可以指导使用API的开发者进行开发，平台并不做校验。

返回结果基础定义

undefined

错误码定义

undefined

注意：

  • 您的API返回结果必须是UTF-8编码，否则中文显示会出现乱码

  • 平台会在您返回的API结果基础上再封装一层

上述步骤完成之后，创建完成，系统提示进入开发。

undefined

查看API

点击API管理列表中某个API的 "查看" 链接可以查看到API的详情，包括API的请求定义、请求参数、请求示例、返回结果、错误码。

002.png | center | 704x293

Untitled 2.png | center | 704x874

编辑API

点击API详情页右上角的 "编辑" 按钮

或者点击API管理列表中某个API的 "编辑" 链接

undefined

undefined
之后就进入到编辑API的流程，其中API名称、API的请求Path是不能改变的，其他内容在API没有上线前可以修改。

undefined

删除API

如果API确认没有被使用，您可以点击 "删除" 链接来删除API，请谨慎操作。

undefined

API版本管理

如果某个服务的前一个版本已经发布上线，那么当前新创建的版本会自动继承上一个版本发布的API，下图中的服务已经有一个上线的1.0.0版本，此时我们再增加一个1.0.1版本。

Untitled 22.png | center | 704x275

1.0.1版本是我们刚刚创建的，我们并没有新增任何API，但是点击1.0.1版本的API管理，进入到1.0.1版本的API列表，已经包含了1.0.0版本中发布上线的API，我们可以对这里自动继承的API进行删除，修改并不会影响1.0.0版本，也可以在自动继承的两个API基础上再新增API，从而完成版本的演进。如果之前的API存在bug，那么请在新版本中对API进行bug fix，然后提醒使用老版本API的开发者切换到新版本中。

007.png | center | 704x293

results matching ""

    No results matching ""