The entire lifecycle of API include: Creation, modification, debugging, release, offline, deletion, etc. The API Gateway provides users with corresponding features.

Create API

The operation of API creation requires the definition of basic information, request information, back-end service information, and return result information of API. The created API, only one copy of API definition, cannot be called directly, and may be called only after being released to a specific environment by the release feature.

Log in to "Console", and click "API Gateway" in the product and service to enter the gateway console. Click "API List" in the left navigation bar, and select "Create API" to start the configuration of API definition.

Configure Basic Information of API

The basic information of API is the overview of API. Baidu AI Cloud users can create a maximum of 1,000 APIs in individual groups. To add more APIs, please submit a ticket.

• Grouping: To designate the group to which the API belongs, please complete the Create Group before API creation. The API uses the attributes of its group, including: Domain name, environment variable, etc.
• API name: The API name cannot be repeated in its group.

• Security authentication:

  • APP AK/SK: When the API caller initiates a request, the APP information included in the request is used to judge whether the current caller has the authority to call the current API.
  • No authentication: Any API caller can initiate a request for the current API (the security is poor. It is not recommended if there is no special requirement). The traffic control feature at the APP and account level cannot be used.
• Its launch in the cloud market is allowed: If this option is ticked, the API may be launched in the cloud market for sale, and the documents may be acquired by all users.
• Description: To basically describe the API, the contents may be used for document display.

Configure Request Information of API

The request information of API describes the method used by the API caller to initiate a request for the current API, including the request method and the request parameter.

Request method

• Protocol: It supports HTTP, HTTPS and WebSocket. The first two items may be selected simultaneously, but WebSocket may be selected only if it is selected. If the HTTPS request is initiated by the group custom domain name, the corresponding certificate should be uploaded in the grouping management, or the calling is abnormal.

• Request Path: For the interface path of the designated request, there is no character restriction, and for the characters unsupported by url (such as: Chinese, and punctuation mark), the escape is not necessary. If being used in the Path, the escape characters can be un-escaped by the API Gateway to original characters for saving and use.

  • Matching of all subpaths: It supports the matching of the subpaths of the current Path.
• HTTP Method: It supports GET, POST, DELETE, PUT, HEAD, TRACE, PATCH, CONNECT, OPTIONS and ANY, and ANY means any Method. When the Method is POST, PUT, PATCH and ANY, the request Body related contents should be configured.
• Query forwarding mode: It supports mapping and pass-through.
• Header forwarding mode: It supports mapping and pass-through.
• Body forwarding mode: It supports mapping and pass-through. The current API Gateway only supports the mapping of the request Body with the contentType of application/x-www-form-urlencoded. Please select "Pass-through" for the request Body of other types.
• Description of Body contents: To basically describe the request Body, the contents may be used for document display.
• Confirmation of Body type: Confirm whether the contentType of request Body is application/x-www-form-urlencoded.

Note:
1.In the request Path, the form of "/[path parameter name]" is used to represent the Path parameter, and should correspond one to one with the Path parameter in the request parameter.

2.In the request of Path configuration, please note that the decollator, "/ path" is not equivalent to "/path/".
3.The matching of subpaths cannot be matched with substrings, for example: The "/path" may be matched with "/path/" and "/path/subPath", but cannot be matched with "/pathAndSubPath".
4.In the configuration of parameter forwarding mode, if the "Parameter Mapping" is selected, the parameters at the corresponding positions should be added in the request parameters. The un-configured request parameters are discarded in the actual request; if the "Parameter Passthrough" is selected, the parameters at the corresponding positions cannot be added in the request parameters, and the parameter at the position can be directly passed through in the actual request.
5.The API Gateway can find duplicates via API, and the rules are: In the same group, two APIs with the same Path, Method, and required query parameter cannot present.

Request parameter

• Parameter name: The parameter name used in the initiation of API calling cannot be repeated.
• Parameter position: It supports PATH, QUERY, HEADER and BODY.
• Parameter type: It supports STRING, INT, LONG, FLOAT, DOUBLE, and BOOLEAN.
• Required: Whether the parameter is required. The PATH position parameter must be required.
• Default value: Default values may be set for optional parameters.
• Example: To take the example values, the contents may be used for document display.
• Description: To describe the parameters, the contents may be used for document display.

• Advanced setting:

  • Maximum length: It is the allowable maximum length for the current parameter.
  • Minimum length: It is the allowable minimum length for the current parameter.
  • Enumeration: The allowable values taken for the current parameter are represented in the form of enumeration, and the different values taken are separated by commas in English.
  • Document visualization: Whether the current parameter is visible in the document.
  • Parameter verification: If the regular expression is used to stipulate the form of the parameter value, the verification is not done currently and may be used only for document display.
  • JSON verification: If the JSON Schema is used to stipulate the form of the parameter value, the verification is not done currently and may be used only for document display.

Note:
1.The parameter with the position of PATH should be configured in the request Path, with the form of "/[path parameter name]".
2.The parameter with the position of BODY refers to the single value in the Body with the contentType of application/x-www-form-urlencoded, not the entire Body.
3.The current API Gateway can verify the parameters in the actual request according to the parameter position, type, requirement, maximum length, and minimum length, and the rest configuration items are used only for document display.

Define WebSocket type request

For the request with the request protocol of WebSocket type, the configuration process is similar to the process above, but only the websocket related configurations are available.

Configure API Back-end Service Information

The API back-end service information describes the service related information provided by API developers, including back-end request method, back-end request parameter, back-end constant parameter, and back-end system parameter. The back-end service supports HTTP(S) and Mock, and different back-end request methods should be configured.

Back-end service of HTTP(S) type

• Back-end service address: The address of host where the designated back-end resource is located supports domain name and IP form and cannot be repeated.

  • Type: They are all instances currently.
  • Weighting: It refers to the weighting of the current address when the multiple designated back-end addresses are polled. The weighting value is an integer value within 1-100, and its default value is 1.It becomes valid when there are multiple back-end addresses.

• Back-end request Path: For the specific path of the designated back-end resource, there is no character restriction, and for the characters unsupported by url (such as: Chinese, and punctuation mark), the escape is not necessary. If being used in the Path, the escape characters can be un-escaped by the API Gateway to original characters for saving and use.

  • Matching of all subpaths: Here may be ticked only after the subpath matching is selected in the API request information.
• HTTP Method: It supports GET, POST, DELETE, PUT, HEAD, TRACE, PATCH, CONNECT, OPTIONS and ANY, and ANY means any Method. When the Method is POST, PUT, PATCH and ANY, the request Body related contents should be configured.
• Back-end timeout: The unit is millisecond. It is an integer value within 1-300000, and its default value is 90000.
• ContentType: The value taking policy for the ContentType header field designated to be forwarded to the back end supports the API Gateway default, user-definition and passthrough. If the Body forwarding mode in the request information is passthrough, the passthrough is required here.
• ContentType value: When the ContentType policy is custom, designate the ContentType value.

Note:
1.In the back-end service address and the back-end request Path, the environment variables may be used by the method of #environment variable name#.
2.In the back-end request Path, the form of "/[path parameter name]" is used to represent the Path parameter, and should correspond one to one with the Path parameter in the back-end request parameter.
3.When the matching of subpaths is ticked simultaneously in the API request method and the back-end request method, the back-end access can pass through the request path.
4.When the ANY method is used simultaneously in the API request method and the back-end request method, the back-end access can pass through the request Method.

Back-end service of Mock type

• Mock return result: It designates the Mock result of the current interface. The ContentType of API Gateway return is "application/json", so it is suggested to fill in the contents in the JSON format.
• HTTP Status Code: It designates the return request code, and it is 200 by default. The valid values include: 200, 201, 202, 203, 204, 205, 206, 300, 301, 302, 303, 304, 305, 307, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 450, 451, 500, 501, 502, 503, 504, 505.
• MOCK Header: it designates the Header to be returned by the current API.

Note: The system parameter and constant parameter may not be configured for the back-end service of Mock type.

Back-end request parameter

Parameter name: It designates the parameter name to be forwarded to the back end, and may not be repeated in all back-end parameters.
Parameter position: It supports PATH, QUERY, HEADER and BODY.

Note:
1.The corresponding input parameter name, the corresponding input parameter position and the corresponding input parameter type are only used for display, and may not be configured.
2.The back-end service parameter should correspond one to one with the parameters in the input parameter definition, and cannot be added manually.
3.The parameter with the position of PATH should be configured in the back-end request Path, with the form of "/[path parameter name]".
4.The parameter with the position of BODY refers to the single value in the Body of KEY/VALUE type, not the entire Body.

Constant parameter of back-end request

• Parameter name: It designates the constant parameter name, and may not be repeated in all back-end parameters.
• Parameter value: It cannot be empty.
• Parameter position: It supports PATH, QUERY, HEADER and BODY.
• Parameter type: It supports STRING, NUMBER and BOOLEAN.

System parameter of back-end request

• Parameter name: It designates the system parameter name, and may not be repeated in all back-end parameters.
• Value of system parameter: It designates the value required by the current system parameter, as shown in the Table below.
• Parameter position: It supports PATH, QUERY, HEADER and BODY.

Value of system parameter	Description
BceClientIp	Client IP of sending the request
BceDomain	Domain name of sending the request
BceRequestHandleTime	Request time (Greenwich Mean Time)
BceAppId	ID of the requested APP
BceRequestId	RequestId
BceHttpSchema	It is the protocol http or https used by the user to call the API.
BceClientUa	User-Agent used in sending the request.
BceProxy	It represents the gateway agent name, and fixed as BceApiGateway.

Define WebSocket type request back end

The configuration of WebSocket type back end is allowed only when the request is defined as WebSocket type.

The meaning of the configuration item of WebSocket is the same as that of the HTTP protocol. The corresponding description can be found in it.

Configure Return Result Information

Currently, the return result information is used only for document display, and doesn't affect the actual forwarding, including the description of return result and that of error code.

Back-end return result

• Return ContentType: It supports JSON, TEXT, BINARY, XML and HTML formats.
• Example of return result: It describes the successful return result of accessing the current API.
• Example of failed return result: It describes the failed return result of accessing the current API.

Description of back-end error code

• Error code: It designates the abnormal codes which may be thrown out by the back-end service, and supports English, numbers. It may be started with English and contains 1-180 characters. It is different from HTTP Status.
• Error message: Description information corresponding to the error code.
• Description: Remark information of the current error code itself. (to be determined)

Modify API

We can modify the API on demand after creating the API.

1.Enter the gateway console. Click "API List" in the left navigation bar.
2.Find the API to be modified, and click "Details" to enter the details page.

3.Click the "Edit" button at the top page to modify the API, and the restriction rules of all configuration items are the same as those of API creation.

Note: The API modification doesn't affect the released API version. If the current modification should become valid at the request of API callers, the modified API should be released again.

Delete API

1.Enter the gateway console. Click "API List" in the left navigation bar.
2.Find the API to be deleted, and click "Delete".

Note: Ensure the API has been offline in all environments before deleting the current API.

Release API

The API definition should be released to the specific environment to enable the definition become valid. The API callers may call the API in the corresponding environment.

1.Enter the gateway console. Click "API List" in the left navigation bar.
2.Find the API to be released, and click "Release".

3.Select the environment where the API is to be released and fill in the release description. The description is mainly for the modification of the currently released version.
4.Click "Release" button to release API.

Note: One API can have only one released version in one environment. When one API is released for multiple times. The latest released version can override the previous valid versions.

API Offline

When the API should stops providing external service, the offline feature may be used to remove the API from a designated environment. API callers cannot continue to use the API in the corresponding environment.

1.Enter the gateway console. Click "API List" in the left navigation bar.
2.Find the API to be offline, and click "Offline". In the "Runtime Environment", we can view the API definitions which have been online in each environment, and determine the environment to be offline.

3.Select the environment to be offline, and click "Offline" button to complete API offline.

Switching of Historical Versions of API

When the API is released, a copy of historical versions of API can be generated to record the detailed definition of API at the release time. By viewing the historical versions, we can select and switch a specific version. The API of this version becomes valid in the corresponding environment, and replaces the previously released versions in the environment.

1.Enter the gateway console. Click "API List" in the left navigation bar.
2.Find the required API, and click "Details" to enter the details page.

3.Click "Release History" in the left navigation bar, and view the historical versions.
4.Select "Switch to the Version" to switch the historical versions. We may select "View" button to view the specific API definition and specify the version to be switched.

Note: The historical versions may be switched only when the API is at the release status.