Application Service > API Gateway > Console User Guide
API Gateway Service
API Gateway service is a unit that allows users to manage APIs served through API Gateway.
Each API Gateway service can manage an API resource and a number of stages, and the API indexes can be checked through dashboard.
Create API Gateway Service
You can enter API Gateway service information and click Create button to create API Gateway service.
- Service Name: The name of the service.
- Service Description: The service description.
- Service ID: A random ID issued to each service.
[NOTE] API Gateway services creation limit
Up to 10 API Gateway Services can be created per project.
View API Gateway Service
- The list of registered API Gateway services appears.
- If you select a service from the list, the list of registered stages appears.
- To manage resources, click the Resource button in the Service Settings column.
- To manage stages, click the Stage button in the Service Settings column.
Delete API Gateway Service
- The list of registered API Gateway services is displayed.
- Select the service from the list, and click the Delete button.
- Click Confirm on the confirmation window, deleted data cannot be restored.
[Caution] When API Gateway service cannot be deleted
API Gateway service cannot be deleted if there is a usage plan connected to the stage of the API Gateway service.
Resource
Resource is the area where you design an API that will serve through API Gateway.
All clients requesting APIs can make a request regarding the APIs defined in the Gateway resource.
Resource manages the resource path and method of the API.
- Resource path: API path
- Resource method: HTTP method
- Plugin: Adds add-ins to the resource path or method.
Create Resource
- To create a resource, click the Create Resource button, or click Create Resource from the menu that appears upon right-clicking the Resource Tree screen on the left.
- Write the Resource Path. The entire path including the written resource path must not exceed 255 characters.
- – e.g./products/, /products/{productsId}, /{proxy+}
- Path Variable: Curly brackets can be used in the Resource path to create a Path Variable.
- Path Variable containing {variable} or child path can be declared as {variable+}.
- Path Variable can be utilized in the plugin and backend endpoint settings.
- {variable} declares the value of the path where the path variable is located.
- e.g./members/{memberId}
- {memberId} path variable value of /members/id1 request becomes id1.
- {variable+} includes the child path where the path variable is located to declare a variable. A child resource path cannot be created in the variable containing the child path.
- e.g./{proxy+}
- {proxy+} path variable value of /members/id1 becomes members/id1.
- Plugin: Select this option if you want to add a plugin that is added to the selected path to the created method as well.
- To create a resource and register a method at the same time, select HTTP method.
- If you make a request to API Gateway with an unregistered resource path, 404 Not Found response is returned.
Import Resource
You can bring the resource through the file format of Swagger v2.0 OpenAPI Specification
1. Click the button Import Resource.
2. Click the Swagger Select File button and choose the file, or directly enter the Swagger content.
3. Click the Apply button.
[Caution] When a resource is imported, the existing resources and models are overwritten
When a resource is imported, all existing resources are deleted and overwritten with the imported resource.
When a resource is imported, all existing models created in the service are deleted and overwritten with the imported model.
[Note] Failing to import stage files exported before Nov. 23, 2021
If you import resources with files downloaded via stage export before Nov. 23, 2021, the operation may fail.
Use the resource import using the newly created file through stage export, or change the existing file with the following:
Modification
1. Convert the plugin configuration string of x-api-nhn-apigateway > plugins in the file to a JSON object.
2. If the CORS plugin configuration string exists in the resource method > x-api-nhn-apigateway > plugins in the file, it must be removed. You cannot configure a CORS plugin on a resource method, and if a CORS plugin is configured in its parent resource path, it is automatically added when importing a resource.
If the guide does not solve the problem, please contact the Customer Center.
Example of failing to import stage files exported before Nov. 23, 2021
- [Example 1] Import failure: Stage export files before Nov. 23, 2021 includes plugin setting of plugins in JSON format strings
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": "{\"frontendEndpointPath\":\"/{proxy+}\",\"backendEndpointPath\":\"/anything/${request.path.proxy+}\"}",
}
}
...
}
- [Example 1] Import success: Stage export file in which JSON format string is modified into JSON object in plugin setting of plugins
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": {
"frontendEndpointPath": "/{proxy+}",
"backendEndpointPath": "/anything/${request.path.proxy+}"
}
}
}
...
}
- [Example 2] Import failure: For stage export files before Nov. 23, 2021, if CORS plugin is configured in resource path, CORS plugin setting is included in child resource method
{
...
"paths": {
"/anything": {
"get": {
...
"x-nhncloud-apigateway": {
"plugins": {
"MOCK": {
"statusCode": 200
},
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
- [Example 2] Import success: Stage export file with CORS plugin setting removed from resource method
{
...
"paths": {
"/anything": {
"get": {
...
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
Create Method
[Note] Resource methods creation limit
Up to 100 methods including all resource paths can be created.
Modify Resources And Methods
- Modify resource path
- Resource path cannot be modified. To modify a path, it must be deleted and created again.
- Modify method
- HTTP method cannot be modified. To modify an HTTP method, it must be deleted and created again.
- Method name, description, and backend endpoint items can be modified.
- To modify, select the method from the resource tree on the left.
- Change the settings and click the Save Changes button.
[Note] Modification of OPTIONS method registered by CORS plugin
OPTIONS method registered by CORS plugin cannot be modified.
Delete Resources And Methods
- Select the resource path and methods you want to delete.
- Clicking the Delete Selected button brings up the Confirm Delete window.
- If you right-click the resource tree on the left, a menu appears. If you click Delete Resource or Delete Method in the menu, a confirmation window appears.
- Click Confirm on the confirmation window. Once deleted, data cannot be recovered.
[Caution] Deletion of resource path
If you delete a resource path, all child resource paths and methods of the selected resource path are deleted.
[Note] Deletion of OPTIONS method registered by CORS plugin
OPTIONS method registered by CORS plugin cannot be deleted.
Apply Stage Resource
To change resources and apply the changed resources to the stage, you must Apply Stage Resource.
- To apply the changed resources to the stage, click the Apply Stage Resource button.
- Select the Stage to apply the changed resources.
- Click the Apply button.
[Caution] Applying stage resource
- To apply a stage resource, one or more stages must exist.
- Once a resource is applied to a stage, the resource cannot be restored to the previous state.
- If the latest resource is already applied to the stage, stage resource cannot be applied.
Add/Delete Plugin
Plugin allows you to add additional functions provided by API Gateway.
- Where to apply plugins
- Plugins can be added to the resource path or method.
- When you add a plugin to a resource path, the plugin is batch applied to the child methods of the selected path.
- When you add a plugin to a method, the plugin is applied to the selected method only.
- Steps for applying plugins
- Plugins can be applied during the Backend Request Pre-Task and Frontend Response Pre-Task steps.
- Backend Request Pre-Task: Applies plugins before passing the API request received by API Gateway to the backend.
- Frontend Response Pre-Task: Applies plugins before the response passed from the backend is forwarded to the frontend.
- Add Plugin
- Click the + Plugin button for the backend request pre-task and frontend response pre-task.
- Click the plugin to add.
- Enter necessary information in the plugin settings and click the Add button.
- To batch apply the plugin to the child path and method (including the selected path), select Overwrite Child Path and Method.
- !Caution: If the plugin is already registered in the child path and method, the settings will be overwritten.
- Click the Save Changes button.
- Delete Plugin
- Select the registered plugins for the backend request pre-task and frontend response pre-task.
- To batch delete the plugin from the child path and method (including the selected path), select Overwrite Child Path and Method.
- Click the Delete button.
- Click the Save Changes button.
[Caution] Saving changes after adding plugins
You must click the Save Changes button after adding plugins to save the changed settings.
Request Parameters
Set request parameters, response types, and content type for each resource method.
Settings are applied to API document.
- Select the resource method.
- Click the Request parameter tab.
- Enter the request parameter items.
- Click the + button on the right side of items to add an item.
- Click the - button on the right side of the item to delete the item.
- Query String, Header, Form Data parameters
- Name: Enter the parameter name.
- Description: Enter the parameter description.
- Data Type: Enter the data type of the parameter.
- Required: Select whether the parameter is required or not.
- Array: Select whether the parameter data is array or not.
- Request Body parameter
- Name: Enter the name of the request body parameter.
- Description: Enter the parameter description.
- Model: Select the Model of the request body.
- Content Type
- Enter the content type (e.g., application/json) of the documents to send to the server.
- Click the Save Changes button.
Response
Set header, request body, and content type for each HTTP response status code.
Settings are applied to API document.
- Select the resource method.
- Click the Response tab.
- Click the Add button of the response HTTP status code to display the additional input screen.
-
Enter the response HTTP status code and description to add.
-
Click the Create button.
- Select the row for the added response HTTP status code.
- Enter the response header and response body for each response HTTP status code.
- Header
- Name: Enter the header name.
- Description: Enter the header description.
- Data Type: Enter the data type of the response header.
- Response Body
- Name: Enter the name of the response body parameter.
- Description: Enter the description of the response body parameter.
- Model: Select the model of the response body.
- Enter the content type.
- Enter the content type (e.g., application/json) of the documents to respond to the client.
- Click the Save Changes button.
Context Variables
The variables defined below can be used when creating methods of resources or setting plugins.
Context Variables |
Description |
${request.clientIp} |
IP of the client that requested API |
${request.path.variable-name} |
Value of a single path variable {variable-name} declared by the resource |
${request.path.variable-name+} |
Value of the path variable including child paths {variable-name+} declared by the resource |
${request.host} |
Request Host header (Example: kr1-example.api.nhncloudservice.com) |
${request.uri} |
Request URI (Example: https://kr1-example.api.nhncloudservice.com/users/userId1) |
${request.uriPath} |
Request path (Example: /users/userId1) |
${request.uriPattern} |
URL pattern to which request is mapped (Example: /users/{userId}) |
${request.scheme} |
Request scheme (http/https) |
${request.httpMethod} |
Request HTTP method (GET, POST ...) |
${request.timestamp} |
Request time (Timestamp) |
${request.queryString.QUERY_STRING_NAME} |
Request query parameter |
${request.header.HEADER_NAME} |
Request header |
${response.httpStatus} |
Response HTTP status code |
${error.resultCode} |
Error code |
${error.resultMessage} |
Error message |
[Caution] Path Variables
You can only use the path variables declared in the selected path and its parent path.
[Note] Use Context Variable
Available in the form ${CONTEXT_VARIABLE} or $!{CONTEXT_VARIABLE}, for CONTEXT_VARIABLE, only defined context variables can be used.
If used as ${CONTEXT_VARIABLE}, the string ${CONTEXT_VARIABLE} will not be replaced if the context variable has no value.
When used as $!, as in $!{CONTEXT_VARIABLE}, it will be replaced with an empty string if the context variable has no value.
[Note] Multiple values in queryString and header are passed to backend endpoints
If multiple values exist for a query parameter and header with the same name, they are combined into a value with a comma (,).
Example: /users?id=user1&id=user2 → /users/id=user1,user2
Plugin
CORS
Allows you to call XMLHttpRequest API within the Cross-Site method.
- The location where the plugins can be applied to: Resource path
- Steps for applying plugins: Backend pre-request task
- CORS plugin setup
- Access-Control-Allow-Credentials: Set to True when requesting with a credential.
- Access-Control-Max-Age: Enter for how long you will be caching the response to preflight in seconds. You can enter a value between 0 and 86400.
- Access-Control-Allow-Origin: Enter the domain of the original server where you can access the resource.
- Enter * to allow all domains. (However, * does not support credentials, so a specific domain must be specified in the allowed origin.)
- To allow multiple domains, separate them by commas (,).
- Domains must be entered in the URI format (scheme, domain, port) (e.g. http://example.nhncloudservice.com:8080).
- Access-Control-Allow-Methods: Set the methods to allow access to resources. To specify multiple methods, separate them by ','.
- Access-Control-Allow-Headers: Set the HTTP header which can be used at the request. To set multiple headers, separate them by ','.
- Access-Control-Expose-Headers: Set the header accessible by the browser (client). To set multiple headers, separate them by ','.
- To find out more about CORS rules, see https://www.w3.org/TR/cors/.
[Caution] CORS plugin
- Registering the CORS plugin also registers the OPTIONS method to the method of the selected path.
If you selected the Overwrite Child Path and Method option, it is also registered in the child path.
If the OPTIONS method is already registered, it is replaced with the OPTIONS method automatically generated by CORS.
- The OPTIONS method registered through the CORS plugin cannot be selected from the resource tree. Also, it cannot be modified or deleted.
- If the CORS plugin gets deleted, the OPTIONS method auto-generated by the CORS plugin is batch deleted.
Adds or changes the request header.
- The location where the plugins can be applied to: Resource path and method
- Steps for applying plugins: Backend request pre-task
- Change Request Header Settings
- You can click the + button to add a header list.
- Enter the header name and value.
- Context Variables declared by the resources can be set for the header value.
[Note] Adding and changing the request header
- Any headers missing from the original request are added.
- Any headers available in the original request are replaced with the header value set by the change request header plugin.
- Any headers available in the original request cannot be deleted.
Deletes the specified header from the headers of the client request and makes a request to the backend.
- The location where the plugins can be applied to: Resource path, method
- Steps for applying plugins: Backend requests pre-task
- Setting up request header deletion
- Click + to add a list of headers.
- Add the name of the header you want to delete.
[Note] Setting up changing and deleting request headers
If you have both the change request header and delete request header plugins set up at the same time, the Delete Request Header will be applied after the Change Request Header is applied.
Change response header plugin adds the header to the backend response or changes the header.
- The location where the plugins can be applied to: Resource path and method
- Steps for applying plugins: Frontend response pre-task
- You can click the + button to add a header list.
- Enter the header name and value.
- Context Variables declared by the resources can be set for the header value.
[Note] Adding and changing the response header
- Any headers missing from the backend endpoint response are added.
- Any headers available in the response of the backend endpoint response are replaced with the header value set by the change request header plugin.
Responds to the client after deleting the specified headers from the backend response headers.
- The location where the plugins can be applied to: Resource paths, methods
- Steps for applying plugins: Frontend response pre-task
- Response header deletion settings
- Click + to add a list of headers.
- Add the name of the header you want to delete.
[Note] Setting up changing and deleting response headers
If you have both the Change Response Headers and Delete Response Headers plugins set up at the same time, Delete Response Headers is applied after you apply Change Response Headers.
Add Request Query String Parameter
Adds a request query string parameter to backend endpoint.
Example: If the parameter name and value are set to 'name' and 'value', name=value query string parameter is added when backend endpoint is requested.
- The location where the plugin can be applied: Resource path, method
- Steps for applying plugins: Backend request pre-task
- + button allows you to add a parameter list.
- Enter the parameter name and value.
- Context Variables declared by the resources can be set for the parameter value.
[Note] Request Query String Parameter
- The requested query string parameter that has the same key as the originally requested query string parameter does not replace the originally requested query string but instead adds the query string parameter.
- The value of the query string parameter is encoded and delivered to the backend endpoint.
Stage
Stage is a phase where resources are deployed.
- A unique Stage URL is issued per stage.
- Stages can be used to categorize services by each service or environment (profile) or used for other purposes.
Create Stage
- From the API Gateway services list, click Stage Settings.
- In the Stage tab, click Create Stage.
- Enter the stage information and click Create.
- Stage Name
- Only lowercase alphanumeric characters are allowed, and the length cannot exceed 30 characters.
- Stage Name is included in Stage URL.
- A default stage is created if no stage name has been written. Stage Name is not included in the Stage URL of the default stage.
- Stage URL: This is a stage URL which can be requested for integration with API Gateway.
- API request client can request APIs through the Stage URL.
- Stage URLs are issued in the following format:
- Default stage: {region}-{api-gateway-service-id}.api.nhncloudservice.com
- {region}: Korea (Pangyo) region (kr1)
- {api-gateway-service-id}: API Gateway Service ID
- Normal stage: {region}-{api-gateway-service-id}-{stage-name}.api.nhncloudservice.com
- {region}: Korea (Pangyo) region (kr1)
- {api-gateway-service-id}: API Gateway Service ID
- {stage-name}: Entered stage name
- Backend endpoint URL
- Writes the backend endpoint URL to which the request received by API Gateway is to be pass.
- You must include the scheme (http:// or https://) when writing the URL.
- You may enter domain address only or include the child path when writing it.
- e.g. https://api.nhn.com , https://api.nhn.com/apis
- If you specify the port directly in the URL, only ports 80, 443, 10000-12000 can be used.
[Note] Stage
- To create a stage, one or more resources methods must have been registered.
- Up to 10 stages can be created per stage.
- When passing requests received by API Gateway to backend endpoint, they are passed to the backend endpoint URL defined in the stage by default.
Modify Stage
- Select the stage to modify.
- Click the Modify Stage button.
- Modify stage information. The stage description and backend endpoint URL can be modified.
- After changing the settings, click the Modify button.
[Caution] Deployment of stage
To apply the modified backend endpoint URL to the API Gateway, the stage needs to be deployed.
Delete Stage
- Select the stage to delete.
- Click the Delete Stage button.
- Click Confirm in the Confirm delete window. This action cannot be canceled.
[Caution] Deletion of stage
- If you delete a stage being used by the service, its request no longer enters the API Gateway.
- Since deleted stage cannot be recovered, make sure it is not being used by the service before deleting it.
- If there is a usage plan connected to the stage, the stage cannot be deleted.
Import Resource
To change resources and apply the changed resources to the stage, you must import resources on the stage management screen.
- To apply the changed resources to the stage, click the Import Resource button.
[Caution] Importing resources
- Once resources are applied to the stage, they cannot be restored to the previous state.
- If there is no change to the resources, the Import Resource button is disabled.
Deploy Stage
To apply the resources and settings for the stage to the API Gateway Services, the stage needs to be deployed.
- In the Stage tab, select the stage to deploy.
- Click the Deploy Stage button.
- The Deploy Stage screen appears.
- Enter the description about the stage deployment. (optional)
- Click the Deploy Stage button.
- See the stage deployment status for the deployment status.
- If it is Successfully Deployed, the deployment is complete.
- If it is Failed to Deploy, then there was an error during deployment . If deployment fails, please try it again. If the issue persists, please contact Customer Center.
Stage Deployment History
You can verify deployment history after stage deployment, and go back stages by setting up Previous Deployment.
- On the Stage tab, select a stage.
- Select Deployment History tab.
- You can verify history of Stage Deployment.
- Deployed Stage: Refers to the deployment history applied to present API Gateway service.
- Base Stage: Refers to the deployment history that becomes the foundation for present stage setup. It is changed when conducting Stage Deployment or Restore Stage.
- Restore Stage: A stage setup of the relevant deployment history. The present Stage Setup is modified.
- Delete: Unnecessary deployment history is deleted.
[Caution] Restore stage to previous deployment history
- If you use Restore Stage, you must deploy stage if you wish to apply it to API Gateway service.
Export Stage
- On the Stage tab, select a stage.
- Select the Export Stage tab.
- Click the Export the Stage button to save the selected stage’s resource in a Swagger file.
API Document
You can check the configuration deployed through stage deployment with the API document.
Refer to API document for details.
IP ACL
API Gateway requests can be allowed/denied for the client IDs specified through IP ACL.
- On the Stage tab, select a stage.
- Select the Setup tab.
- Select the Stage a path or method on the Stage Tree screen.
- Activate (On) the IP ACL.
- Set up the IP ACL.
- IP Access Control Type
- Allow: Only allow access of specific IPs, and deny all the other IPs. (Whitelist method)
- Deny: Only deny access of specific IPs, and allow all the other IPs. (Blacklist method)
- IP access target
- You can choose between single input or bulk input to easily register the IP list.
- IP access targets can be entered as IPv4's single IP or CIDR.
- Single IP: 10.0.0.1
- CIDR example: 10.0.0.1/24
[Note] IP ACLs registration count limit and client IP check
- For IP ACL, up to 100 IP access targets can be entered.
- If the source IP of the client has been changed by network address translation (NAT), please note that the IP ACLs will be checked based on the changed IP.
Authentication > HMAC
HMAC authentication prevents requests received by the API Gateway being tampered by middle attackers, and also prevents reply attack by setting the expiration period for the requests.
- On the Stage tab, select a stage.
- Select the Setup tab.
- Select the Stage root(/) path on the Stage Tree screen.
- In the authentication, select HMAC.
- Enter the HMAC setup.
- Secret key: It is a secret key for encrypting SignToString. Make sure the key is not exposed to others.
- Request expiration (sec): Denies the request that exceeds the bidirectional time (before and after the past/future point of the request time) of the set expiration. If the request expiration is set to 0, the API Gateway does not check the expiration time.
- Required validation header list: Write the header list which must be included in the API request validation. When entering a number of lists, separate them by commas (,).
[Note] HMAC authentication failure response
If HMAC authentication fails, 401 Unauthorized response is returned.
[Caution] Request expiration
- If set to 0, it does not check the request expiration. It this case, it can be vulnerable to reply attacks.
- If the expiration is too short, the expiration can be elapsed before the API Gateway validates the request, which could lead to the request being denied. It is recommended to set the time to 10 seconds or longer than the expected request expiration.
- You must check if the NTP (Network Time Protocol, NTP) of the API client is valid because requests can be denied due to non-synced time information.
[Note] Required validation header
If you have set the required validation header, it validates if the required validation header is included in the request and if it is the value containing the header in the signature while validating the API request.
During the setup, make sure the required validation header is included when creating a request and signature.
API Client Actions For HMAC Authentication
To perform HMAC authentication, the API request client must include the following validation header and request time header when making the request.
Header Name |
Header Value |
Authorization |
hmac algorithm="<encrypt_algorithm>", headers="<validation_headers>", signature="<base64_digest>" |
x-nhn-date |
ISO8601 time format |
[Note] x-nhn-date's ISO8601 format
- UTC format: yyyy-MM-dd'T'HH:mm:ssZ
- UTC-based time offset forma: yyyy-MM-dd'T'HH:mm:ss±hh:mm
-
If the authorization or x-nhn-date header is not included in the request, HMAC authentication fails.
-
Authorization header values are created as shown below:
Credential name |
Value |
algorithm |
HmacSHA256 or HmacSHA1 |
headers |
When proceeding with HMAC authentication, the header list console must include the headers registered in the HMAC validation required header. |
signature |
A value encoded with Base64 after encrypting the SiginToString string |
[HTTP Method]\n
[Request URL]\n
[Request datetime]\n
[header1-name]:[value1]\n
[header2-name]:[value1,value2...]\n
...
SignToString Example
- HTTP request original body
GET /members?isEnable=false&type=public HTTP/1.1
Host: http://kr1-example.api.nhncloudservice.com
x-nhn-date: 2021-02-23T00:00:00+09:00
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
- SignToString regarding the HTTP request original body
GET
/members?isEnable=false&type=public
2021-02-23T00:00:00+09:00
host:kr1-example.api.nhncloudservice.com
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
- signature generation code example (Java): A value encoded with Base64 after encrypting the SignToString with HMAC
String secretKey = "Secret key set to HMAC";
// encryption algorithm HmacSHA1 or HmacSHA256
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
String message = "StringToSign";
byte[] rawHmac;
rawHmac = mac.doFinal(message.getBytes());
String authorization = new String(Base64.encodeBase64(rawHmac));
- Complete HMAC authentication header
Authorization:hmac algorithm="HmacSHA256", headers="host,x-nhn-client-id,x-nhn-client-ip" , signature="V5Dye9kgG3tvZOOZertd5LXE0q8CcJGXCxEFCR71hUE="
x-nhn-date:2021-02-23T00:00:00+09:00
[Caution] Cautions when generating SignToString
- SignToString Each field is separated by new-line characters(\n).
- Headers defined in headers must be included when generating SignToString.
- If the defined header is missing from the headers, [header name] and [header value] are not included in the SignToString generation.
- SignToString must be generated in the order defined in the headers.
- e.g. If headers="header1, header2", the headers must be added in the order of header1, header2 when generating the SignToString.
- The entire header name of the SignToString must be changed to lowercase before generating it.
- e.g. X-NHN-Header → x-nhn-header
- If there are a number of header values, they must be separated by commas (,) when writing them.
- e.g. header1-name:header1-value1,header1-value2
- The header names and values are separated by colon (:), and do not include space in-between when separating the values.
Authentication > JWT
Verifies the signature and claim of JWT token. Token values can be used without token verification for user services.
- On the Stage tab, select a stage.
- Select the Setup tab.
- Select the Stage root(/) path on the Stage Tree screen.
- In the authentication, select JWT.
- Enter the JWT setup.
- Token Encryption Algorithm: Select the encryption algorithm used to sign the token. Encryption algorithm supports HS256 and RS256.
- HS256 Token Algorithm
- Secret Key: Enter the secret key used to sign the token. Secret key with the length of 256 or above is recommended.
- RS256 Token Algorithm
- Public Key (PEM): Enter the public key to verify the token. It must be entered in PEM format.
- JWKS URI: Enter the HTTP JWKS (JSON Web Key Set) URI from which API Gateway retrieves the JWKS object required for token signature verification and encryption.
- Claim Verification Condition
- Enter the claim verification conditions for the registered claim of the token payload.
- For more information on the registered claims, see RFC7519-4.1.Registered Claim Names.
- If any one of the claim verification conditions is not met, verification fails.
- Claim: Name of the registered claim of the token payload.
- Data Type and Claim Value:
- Array: Enter multiple strings separated by commas (,). If the string array contains at least one claim value of the request token, the verification succeeds.
- String: Enter a single string. If it matches the claim value of the request token, the verification succeeds.
- Required: Verification fails if claims do not exist in the request token when selected. A disabled checkbox cannot be selected or cleared.
- Value Verification: If a claim exists in the request token when selected, verification will proceed to check whether the set claim value includes or matches the claim or not. A disabled checkbox cannot be selected or cleared.
- Verification Time Limit (sec): Apply verification time limit to verify exp and nbf claims of the request token. You can enter any number between 0 and 86,400 (sec).
- Deploy the stage.
- When requesting API Gateway, first add a JWT token to the Authorization Header and then make a request.
Header name |
Header value |
Authorization |
Bearer "<jwt-token>" |
[Note] JWT Token Authentication Failure Response
If the authentication of JWT token fails, 401 Unauthorized response is returned.
For more information, see the Gateway Error Code document.
[Note] Creating JWT Token
API Gateway only verifies whether the JWT token signature and claims match or not. A JWT Token must be created via user applications or authentication service providers.
To learn how to create a JWT token for the purpose of development and testing, see JWT Token Debugger.
[Note] JWKS (JSON Web Key Set) URI description and precautions
JWKS is the JSON data for the JWK (JSON Web Key) encryption key that the API Gateway needs to verify token signatures.
For more details and specifications on JWK, please refer to the RFC7515 document.
The selected JWKS URI must be disclosed so that the API Gateway can access it, and should not be blocked with networks, firewalls, etc.
The selected JWKS URI must be operated so that the API Gateway can always access it.
If you specify the port directly in the JWKS URI, only ports 80, 443, 10000-12000 can be used.
[Caution] JWKS Caching
API Gateway caches JWKS URI's response for 5 minutes.
Due to caching by API Gateway, it may take a maximum of 5 minutes for modifications in JWKS to be reflected in API Gateway.
Access Log
This is a feature that lets you store API Gateway's access logs in the Log & Crash Search service.
- On the Stage tab, select a stage.
- Select the Settings tab.
- In the stage tree view, select the root (/) path of the stage.
- Enable (On) the access log feature.
- If you are not using the Log & Crash Search service, click Enable Log & Crash Search Service to enable the service.
- Click Modify to save your settings.
- After running Deploy Stage, access logs are stored in the Log & Crash Search service.
Access logs can be found in the Log & Crash Search service.
- Go to the Log & Crash Search service console page.
- Retrieve logs with logType field "NNH Cloud-API Gateway" in the Log & Crash Search service.
- The content of fields to be stored in Log & Crash Search is as follows.
Field |
Description |
longRequestTime |
Timestamp of the request date and time |
requestPath |
Request path |
resourcePath |
Resource path to which the request is mapped |
requestHttpMethod |
Request HTTP method |
clientIp |
Request client IP |
responseHttpStatus |
Response HTTP status code |
body |
String in the format {clientIp} - [{requestTime}] "{requestHttpMethod} {requestPath}" {responseHttpStatusCode} |
host |
Request host: Domain of the stage URL |
logType |
Log type: A fixed value of "NHN Cloud-APIGateway" |
logLevel |
Log level: "INFO" for response status code lower than 400, "ERROR" for response status code 400 or higher |
errorCode |
Gateway error code if an error occurred in API Gateway, empty value if no error occurred |
errorMessage |
Gateway error message if an error occurred in API Gateway, empty value if no error occurred |
[Note] Log & Crash Search usage fee information
Access logs are stored in the Log & Crash Search service, and the Log & Crash Search service usage fee is charged separately.
Refer to the links below for the Log & Crash Search service introduction and usage fee.
Go to the Log & Crash Search service introduction
Go to the Log & Crash Search usage fee
[Caution] Notification on disabling the Log & Crash Search service while using the access log feature
If you disable the Log & Crash Search service while using the access log feature, the access logs are no longer stored and the access log feature is automatically disabled.
To use the access log feature again, enable the Log & Crash Search service and then enable the access log feature again.
Pre-call API
Pre-call API determines whether or not to call the backend endpoint depending on the call response code after calling the user-designated API before calling the backend endpoint.
Pre-call API including the request headers that came in through the API Gateway is called, and the Pre-call API will return the response code depending on the forwarded header content.
Backend endpoint is called if Pre-call API’s response code is 200; Pre-call API’s response result is returned if the response code is not 200.
If Pre-call API call fails, it returns an error.
This can be used in a situation where authentication through a separate API call is required before calling the backend endpoint or there is another API to be called.
- On the Stage tab, select a stage.
- Select the Setup tab.
- In the Stage Tree screen, select the path or method to apply the Pre-call API.
- Pre-call API set in a path is applied to all child paths and method calls defined under the path.
- Pre-call API set in a method is applied when calling the method, but Pre-call API set in the root path is not applied.
- Activate the Pre-call API.
- Enter the method type and URL for Pre-call API.
- If you specify the port directly in the URL, only ports 80, 443, 10000-12000 can be used.
- Cache time limit can be set to 86400 sec at maximum, and the response results are cached for the period specified by the entered number (seconds).
- If the cache time limit it set to 0, response results for Pre-call API will not be cached and Pre-call API will be called for every request.
[Note] Response Result Caching for Pre-call API
Response results are only cached if Pre-call API’s response result code is 200.
If the response result code is not 200, response results will not be cached even if the cache time limit is set.
Backend Endpoint URL Override
When passing the requests received by the API Gateway to the backend endpoint, the requests are (by default) passed to the backend endpoint URL defined in the stage.
To Override the backend endpoint URL concerning certain path or method, set up the redefinition of backend endpoint URL.
- On the Stage tab, select a stage.
- Select the Setup tab.
- Select the path or method to redefine the backend endpoint URL in the Stage Tree screen.
- Turn on override of the backend endpoint URL.
- Writes the backend endpoint URL to which the request received by API Gateway is to be pass.
- Can include the child path in it.
- e.g. https://api.nhn.com , https://api.nhn.com/apis
- If you specify the port directly in the URL, only ports 80, 443, 10000-12000 can be used.
Request Number Limit
Requests received by the API gateway every second can be adjusted using the request number limit, and the backend endpoint can be protected via the request number limit.
- On the Stage tab, select a stage.
- Select the Setup tab.
- On the Stage Tree screen, select the root (/) path or method of the stage.
- If set for the root path, request number limit will be applied to the stage.
- If set for the method, request number limit will be applied to each method. Request number limit set for the parent path will be ignored.
- Turn the request number limit On.
- Set the request number limit.
- Requests per Second: Enter the maximum number of requests that can be called in seconds.
- Request Limit Key: The default request limit key is stage when set for the root, and method when set for the method. A request limit key can be added to the default request limit key.
- None: Limits requests to default request limit key.
- Path Variable: Limits requests for the default request limit key and different path variables. It can be set if the selected method path has a path variable.
- IP: Limits requests for each default request limit key and request client IP.
- Header: Limits requests for each default request limit key and set header name value.
[Note] Request Number Limit Response
If requests per second is exceeded, the response of 429 Too Many Requests is returned.
[Caution] Request Limit Key
When using the request limit key, the request must contain the specified key. For example, if header is selected for the request limit key and the X-NHN-CLOUD value is entered, the request header must contain X-NHN-CLOUD.
If the request limit key cannot be found from the request, the request number limit is not applied.
[Caution] Accuracy of Requests Per Second
- The requests per seconds set and the actual number of requests could slightly differ depending on the time delivered to API Gateway, request processing time, and other factors.
Request Restriction Policy
Applies registered request restriction policy to stage resource paths or methods. For more information, see Request Restriction Policy.
- Select a stage on Stage tab.
- Select Settings tab.
- On Stage Tree screen, select a path or method you want to apply request restriction policy.
- Enables (On) request restriction policy.
- Select a request restriction policy to apply and click the Modify button to save it.
- Click the Deploy Stage button. When the stage deployment is complete, the set request restriction policy works.
API Key
When making an API request to API Gateway, it is restricted to only the specified API key to be requested.
- Examines if it is a valid API key value.
- Only the API key connected to the stage of the usage plan can request the API of the stage. (For details, refer to Usage Plan > Connect Stage to Usage Plan.)
- Examines the request limit of the usage plan the API key is connected to. (For details on how to set the request limit of a usage plan, refer to Usage Plan > Create Usage Plan.)
[Note] API key failure response
The API request is rejected when the API key value is not included in the requested header, of its invalid, or exceeds the usage limit.
For more information, see the Gateway Error Code document.
- On the Stage tab, select a stage.
- Select the Settings tab.
- Select the path or method to enable API key in the stage tree screen.
- The API key set in a path is applied to all child paths and method calls defined under the path.
- Enable the API key.
- Deploy the stage.
- When requesting API, it is requested by adding the API key value to the x-nhn-apikey header.
Header name |
Header value |
x-nhn-apikey |
<primary api key or secondary api key> |
Validate Requests
Validates the client request according to the request parameter settings set in the API Gateway resource.
If validation fails, it returns an error response and does not forward the request to the backend endpoint.
- Select Resource > Resource Method.
-
In Request parameters, set the information about the request parameters to validate. See below for the types of parameters that are supported for validation and how they are validated.
-
Query String
- Validates whether it is required. Data type and whether it is an array are not validated.
- Query string names are validated for case sensitivity.
-
Header
- Validates only whether it is required. Data types are not validated.
- Header names are validated case-insensitive.
-
Form data
- Validates form data only if the Content-Type in the request header is
application/x-www-form-urlencoded
.
- Validates only whether it is required. Data type and whether it is an array are not validated.
-
Request Body
- Validates the request body only if the request Content-Type is
application/json
.
- Validates the Request Body based on the Json Schema(Draft4) of the specified model.
-
Content type
- Validates the form data or request body if it is set. If the request is made with a type other than the specified Content-Type, validation will fail.
- If there is no Content-Type specified or it is set to
*/*
, the content type is not validated.
-
Click Apply stage resource to apply to the stage.
- Select Stage tab.
- On the Stage Tree screen, select the route or method for which you want to enable the request validator.
- The request validation you set on a route is enforced for all subdefined child routes and method calls.
- Enable (on) the request validator.
- Deploy the stage.
- The client's request is denied or allowed at the API Gateway level based on the set request parameters.
[Caution] Setting form data and request body
You can't set form data and request body at the same time.
You cannot support application/x-www-form-urlencoded and application/json as Content-Type on the same resource at the same time, so you must separate resources based on content type.
Model
You can define a model to specify the format of body that you can use in the request parameters and the response.
Create Model
- Click Resource in the service settings column from the list of API Gateway services.
- In the Model tab, click the Create model button.
- Enter the model information and click Create.
- Model name:
- The name of the model. It cannot be the same as the name of the existing model.
- Only numbers and English letters can be entered, up to 50 characters.
- Model description: It is the description of the model. (optional)
- Model schema:
- Define the structure that the model can have.
- Use JSON Schema draft-04 for the model schema definition.
Edit Model
- Select the model to edit from the list of models.
- Click the Edit button.
- Edit the model information. Items that can be edited are model description and model schema.
- After changing the settings, click the Edit button.
Delete Model
- Select the model to delete from the list of models.
- Click the Delete button.
- The model cannot be deleted while being used in the request parameters or response.
- Click Confirm on the confirmation window. Deleted data cannot be restored.
Request Restriction Policy
request restriction policy is a feature that allows you to set IP ACLs and request count limits based on a request's path variable or request header value.
Create request restriction policy
- In the list of API Gateway services, click Resource in Service Settings column.
- On Request Restriction Policy tab, click Create Request Restriction Policy.
- Enter request restriction policy information.
- Request Restriction Policy Name: Enter the name of request restriction policy
- Request Restriction Key Type: Select the location of the request restriction key value to which the request restriction policy applies.
- Path variable: Select a path variable to set the request restriction policy according to the value of the path variable in the requested path.
- Request header: Select a request header to set a request restriction policy according to the value of specific request header.
- Request Restriction Key: Enter the request restriction key according to the request restriction key type.
- When request restriction key type is a path variable: Enter the name for the path variable. For example, when you set the request restriction policy for the path variable {memberId} in resource path {memberId}, type memberId.
- When request restriction key type is a request header: Enter the header name where the restriction key value is located.
- Requests per second by default: When a request restriction policy is not set for the request restriction key value, set the request per second restriction to be applied by default
- If you do not enter it, you do not apply the request count restriction for the key values of unregistered request restriction.
- You can set it from 1 to 5000.
- Response Remaining Token Count: When the request restriction is set, the number of remaining tokens that can be requested is passed to the 'X-NHN-RateLimit-Remaining' response header.
[Note] Limit the number of request restriction policies created
Request restriction policies can be created up to 10 per API Gateway service.
Apply request restriction policy to Stage Resources
- Select a stage on Stage tab.
- Select Settings tab.
- On Stage Tree screen, select a path or method you want to apply request restriction policy.
- Enables (On) request restriction policy.
- Select request restriction policy to apply and click the Modify button.
- Click the Deploy Stage button. When the stage deployment is complete, the set request restriction policy works.
Modify request restriction policy
Allows you to modify the name of the request restriction policy, the default number of request restrictions per second, and the number of remaining tokens.
The request restriction key type and request restriction key cannot be modified.
- From the list of request restriction, select the request restriction policy that you want to modify.
- Click Modify Request Restriction Policy.
- Modify the request restriction policy information and click the Modify button.
Delete request restriction policy
- From the list of request restriction, select the request restriction policy that you want to modify.
- Click Delete Request Restriction Policy.
- Click Confirm on the confirmation window. Deleted data cannot be recovered.
[Note] Request restriction policy cannot be deleted
When the request restriction policy to delete is set on the stage or is included in the deployed stage, it cannot be deleted.
To delete, delete the request restriction policy set on the stage, deploy the stage and then delete it.
Create request restriction key value
Create key value of request restriction policy Depending on the restriction key value, you can set different IP ACLs and request count limits.
1. Select the request restriction policy to which you want to add the request restriction key value.
2. On the bottom tab, click the Create Request Restriction Key Value button.
3. Enter the information of request restriction key value.
- Request Restriction Key Value: Enter a request restriction key value. Allows you to set IP ACLs and request count limits for each request restriction key value.
- Requests Per Second: Enter the request restriction value per second for the request restriction key value.
- If not entered, it is limited to the default number of requests per second value set in the request restriction policy.
- IP Access Control Type:- Allow: Allows you to access only to the specified IP and denies all remaining IPs. (Whitelist method)
- Reject: Allows access only to the specified IP and allows all remaining IPs. (Blacklist method)
- IP Access Destination:
- You can easily register an IP list by selecting either single entry or bulk entry method.
- IP access destinations can be entered as a single IP or CIDR for IPv4.
- Single IP example: 10.0.0.1
- CIDR example: 10.0.0.1/24
- IP ACL access control does not work unless you enter any IP access destinations.
Modify request restriction key value
Modify the request restriction per second, IP access control type, and IP access destination. Cannot modify request restriction key value
- On the bottom tab of request restriction policy, select a request restriction key value row to modify.
- Click Modify Request Restriction Key Value button.
- Modify request restriction key value and click Modify button.
Delete request restriction key value
- From the request restriction key value list, select the request restriction key value to delete.
- Click the Delete Request Restriction Key Value button
- Click the Confirm button on the confirmation window. Deleted data cannot be recovered.
Gateway response
Allows users to redefine the error response settings defined by the gateway.
Redefine gateway response
- Click Resource in the service settings column from the list of API Gateway services.
- On the Gateway Response tab, click the type of gateway response you want to set up.
- Enter the response information.
- Response HTTP status code: Enter the response HTTP status code (required).
- Response header: Enter a name and value for the response header.
- Response body template: Enter the content type and corresponding response body.
- Content type: Enter the type of content the user is requesting, that is, the value of the Accept header in the request.
- Response body: Enter the body of the gateway response to return in response to the value of the Accept header in the request.
- You can set context variables in the header value and response body.
[Note] Apply gateway responses
Changed gateway responses are applied after a stage deployment in the shape they were in at the time of deployment.
Reset gateway response
- In the Gateway responses list, select the type of error you want to reset.
- Click Reset Defaults.
- Click Confirm on the confirmation window. The deleted data cannot be recovered.
Gateway response type
Check API Call
- With the Setup tab within the Stage tab, select the Stage Tree method.
- See the Stage URL on the right.
- Call the API with the HTTP method where the Stage URL is specified.
- Example:
- Method: GET
- Stage URL: https://kr1-xxxxx-test.api.nhncloudservice.com/example
curl --request GET 'https://kr1-xxxxx-test.api.nhncloudservice.com/example'
[Caution] Stage deployment
To call the API, there must be a deployed stage with the status: Successfully Deployed.
[Note] If the API is not called properly
- If 404 NotFound HTTP status code is returned:
1. See if the stage deployment status is Deployed.
2. See if the request method and stage URL/path are correct.
3. In the backend endpoint service, see if there is a request URL regarding the backend endpoint URL path.
- As for other error codes, see Gateway Error Code documentation.
[Caution] API Call constraints
- In the Gateway client, the request size with the API Gateway is restricted to max. 10MB. This value cannot be adjusted.
- In the API Gateway, the response size of the Gateway client is max. 10MB. This value cannot be adjusted.
- Response timeout for the request is max. 60 seconds. If there is a response delay in the backend endpoint service, a timeout may occur.
[Caution] API Gateway request ban policy
- If the endpoint service does not respond or continues to cause delayed response (over 60 sec) as a way of protecting the API Gateway Services and backend endpoint service, the request relating to the backend endpoint service is temporarily denied.
- It is not banned by the internal errors (4xx, 5xx, etc.) of the backend endpoint service.
- It is not recommended to link the backend endpoint service if it is not properly operable or if the delayed response (timeout) persists for over 60 seconds.
API Document
You can use the API document to manage the specification of the API registered in API Gateway as a web page document.
Publish API document
Here is the process of publishing API documentation.
- Click Model tab from the resource setting page to request and register the model of the body.
- Select the resource method from the resource setting page and enter the request parameters and response.
- Click Apply stage resource to apply the changed resource details to the stage.
- Click Deploy stage button of the stage setting page.
- Click API document tab of the stage setting page.
- Select the publish type of the API document.
- Publish type: You can set access restrictions for the API document.
- Public: Access to the API document is allowed without access restrictions.
- Private: Only users who are accessible to console can access the API document.
- The API document is available at the URL that appears in the Publish link.
[Note] Stage deployment and API document publishing
- An API document is published after the initial stage deployment, with the initial publishing type set to Private.
- The API document is updated to the configuration deployed when a stage deployment is performed.
[Caution] CORS setting when testing API calls from a published API document
- Since the domain address of the published API document and the domain address of the calling API are different, CORS setting might be necessary to test your calls within the API document.
- Example:
Access-Control-Allow-Origin: https://kr1-docs-apigw.api.nhncloudservice.com
Access-Control-Allow-Method: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS
Access-Control-Allow-Headers: Authorization, x-nhn-apikey, x-nhn-date
Dashboard
Check the API statistical indexes by API Gateway Service and API key using the dashboard.
Stage Tab
- Go to the Dashboard tab.
- Move to the Stage tab.
- Select the API Gateway Service to view the statistics.
- From the list, select the stage to views statistics.
- In the Stage Statistics tab at the bottom, there are statistical indexes for the stage.
- In the Resources Statistics tab at the bottom, there are statistical indexes for each HTTP method and path.
Note on Statistical Data
- Max. Search Period
- Only statistical data for the last 90 days can be viewed.
- Statistical Data Generation Cycle
- Statistical data of all time-unit(1 min./10 min./1 hr./1 day) is renewed every minute.
- The generation of statistical data can be delayed depending on the size of the data.
Stage Statistics
- Graph Display Standard
- The units of the statistics are displayed as the following depending on the search period.
- Less than 1 hour: unit of 1 minute
- Longer than 1 hour - less than 1 day: unit of 10 minutes
- Longer than 1 day - less than 1 week: unit of 1 hour
- Longer than 1 week: unit of 1 day
- Statistical Graph
- Number of successful API calls: Number of API calls with the responded HTTP status code of 2XX, 3XX
- Number of failed API calls: Number of API calls with the responded HTTP status code of 4XX, 5XX
- Average response time (ms): The average time spent from the point where the request entered the API Gateway to the point where the response was given to the API request client
- Network outbound traffic: The byte size of the data responded with the API request client at the API Gateway
Resource Statistics
You can see more detailed statistical indexes categorized by resource path and HTTP method.
- HTTP method: Requested HTTP method
- Path: Resource path mapped with the request
- Number of successful API calls: Number of API calls with the responded HTTP status code of 2XX, 3XX
- Number of failed API calls: Number of API calls with the responded HTTP status code of 4XX, 5XX
- HTTP 2XX~5XX code: Number of API calls by status code group
- Number of immediate responses at the API Gateway: Number of API calls responded at the API Gateway without passing the request to the backend endpoint service
- Average response time (ms): The average time spent from the point where the request entered the API Gateway to the point where the response was given to the API request client
- Network outbound traffic: The byte size of the data responded with the API request client at the API Gateway
API Key Statistics
The number of calls can be checked for each API key on a daily graph
- Go to the Dashboard tab.
- Go to the API Key tab.
- Select the API Key to view the statistics.
- Graph Display Standard
- The search period can be set in units of day(s) and displayed in units of day(s).
- Statistical Graph
- API Call Count: The count of all API calls where the API key was used
- Count of immediate responses at the API Gateway: Number of API calls responded at the API Gateway without passing API Gateway plugins or usage limit
Usage Plan
Limit the ability to request stage APIs only by API key connected to the stage of the usage plan, the same usage limit can be applied to each connected API key in the usage control settings.
- The following process is needed to apply the usage plan in the API Gateway service.
Create Usage Plan -> Connect Stage to Usage Plan -> Connect API Key to Stage Connected to Usage Plan -> Enable API Key in Stage Settings
- See below for details on creating a usage plan and connecting stage and API key.
Create Usage Plan
- Click the Create Usage Plan button in the usage plan list.
- Enter the usage plan information and click Create.
- Name of Usage Plan: The name of usage plan.
- Description of Usage Plan: The description of usage plan. (Optional)
- Requests per Second: Enter the maximum number of requests that can be called in seconds.(Optional)
- Quota Period Unit: Enter the maximum number of requests per day/month. (Optional)
- Request Quota: Set the quota period unit to enter the maximum number of requests during the specified quota period.
[Note] Reset request quota limits
The request quota resets on the 1st of each month(monthly) and every day (daily) at UTC 00:00:00.
Edit Usage Plan
- Select the usage plan to be edited in the usage plan list.
- Click the Edit button.
- Edit the usage plan information
- After changing the settings, click the Edit button.
[Caution] Edit usage plan request control settings
When editing the limited requests per second and request quota in the usage plan, it will be reflected in the connected API without a separate process.
If you modify the quota period unit to “day” or “month,” the usage of the connected API Key request quota is maintained. If the request quota limit is lowered, the usage may be exceeded.
If the quota period unit is modified to “None,” the requested quota usage of the associated API keys is initialized.
Delete Usage Plan
- Select the usage plan to delete in the usage plan list.
- Click the Delete button and the Confirm Delete window will be displayed.
- Click the OK button on the confirmation window. Deleted data cannot be restored.
[Note] Usage plan cannot be deleted when connected to a stage
Usage plan can be deleted after disconnecting all stages that are connected to the usage plan.
Connect Stage to Usage Plan
Connect a stage to the usage plan to define which stages the API key can request.
- Click the Name link in the Usage Plan Name column in the usage plan list.
- Click the Connect Stage button.
- Click the OK button after selecting the API Gateway service and stage.
[Note] Already connected stage
The already connected stage is not included in the selection list.
Disable Stage Connected to the Usage Plan
- Click the Name link in the Usage Plan Name column in the usage plan list.
- Select the stage in the Connected Stage list to disconnect.
- Click the Disconnect Stage button.
- Click the OK button when the confirmation window appears.
[Note] If there is an API key connected, stage cannot be disabled
In order to disable the stage connected to the usage plan, all API keys connected to the stage must be disabled.
Connect API Key
Connect the API key to call the API of a stage connected to the usage plan.
- Click the Name link in the Usage Plan Name column in the usage plan list.
- Select the stage in the Connected Stage list to connect to the API key.
- Click the Connect API Key button at the bottom
- After selecting the API key to be added, click the OK button.
[Note] API keys connected to the same stage of different usage plans do not appear in the selection list and cannot be connected.
Disconnect API Key
- Click the Name link in the Usage Plan Name column in the usage plan list.
- From the Connected Stage list, select the stage to disconnect the API Key.
- After selecting the API key to disconnect from the bottom list, click the Disconnect API Key button.
- Click the OK button on the confirmation window.
Change the Usage Plan of API Key
- Click the Name link in the Usage Plan Name column in the usage plan list.
- Select the stage that has the API key with the usage plan to be changed in the Connected Stage.
- After selecting the API key with the usage plan to be changed from the bottom list, click the Change Usage Plan button.
- Click the OK button after selecting the usage plan to be changed.
[Note] The selected stage can only be changed to a different usage plan than it is connected to.
[Caution] Initialize usage of API Key request quota when changing the usage plan
If the quota period unit is changed to a “daily” or “monthly” usage plan, the requested quota usage of the associated API Key remains. The usage may be exceeded if changed to the usage plan with a low request quota limit.
If changing to the usage plan with a quota period unit of “None,” the requested quota usage of the associated API keys is initialized.
API Key
- API key manages the string values for API gateway service API access that is connected to the usage plan and stage.
- When requesting API, primary API key and secondary API key can be used as API key value.
Create API Key
- Click the Create Usage Plan button in the API key list.
- Enter the API key information and click the Create button.
- Name of API Key: The name of the API key.
- Description of API Key: The description of API key. (Optional)
- Status of API Key: Select the status of API key.
- ACTIVE: API key is active and can be used.
- INACTIVE: API key is inactive and cannot be used.
- Primary API Key: When selected user customization, it is generated by directly entering the Primary Key value. When not selected, it is automatically generated as an arbitrary string.
- Secondary API Key: When selected user customization, it is generated by directly entering the Secondary Key value. When not selected, it is automatically generated as an arbitrary string.
[Caution] Custom Primary/Secondary API Key
For custom Primary/Secondary API Key, it is generated with a string of at least 10 alphanumeric characters and numbers.
Must be unique across API Gateway services.
It is recommended to make the keys complicated and not to be exposed.
Export API Key
Export a registered API Key in CSV format file.
- On the API Key list page, click the Export button.
- Download CSV file.
[Note] Only API Keys that are queried in API Key list are exported to a file.
Import API Key
Import API keys with CSV format file.
- On API Key list page, click Import button and then click the Select File button to select CSV file to import.
- A list of API keys registered based on CSV files is displayed on the screen.
- If the imported data includes some parts to be modified, the data cannot be imported.
- Click the Import button.
[Note] Import failed when API Key is duplicated
All API keys Importing fails if duplicate Primary API Key and Secondary API Key exists. Please modify the duplicate API key and import it again.
Edit API Key
- Select the API key to edit in the API key list.
- Click the Edit button.
- Edit the API key. Items that can be edited are Name of API Key, Description of API Key, and Status of API Key.
- After changing the settings, click the Edit button.
[Caution] Edit status of API key
If the status of API key is changed to INACTIVE, the API key cannot be used.
Delete API Key
- Select the API key to be deleted from the API key list.
- Click the Delete button and the Confirm Delete window will be displayed.
- Click the OK button on the confirmation window. Deleted data cannot be restored.
[Note] If there are connected usage plan and stage, it cannot be deleted
The API key cannot be deleted if there are connected usage plan and stage.
Regenerate API Key
When requesting API, primary API key and secondary API key that are used as API key value can be regenerated.
- Select the API key in the API key list.
- Go to the API Key tab at the bottom.
- Click the Regenerate button next to the primary API key and secondary API key list and the confirmation window will be displayed.
- Click the OK button when the confirmation window appears.
- If you selected Custom, enter your own API Key value to reissue. If not selected, it will be automatically reissued as a random string.
- The existing API key value is no longer valid when regenerated.
Stage Connected to API Key
- Select the API key in the API key list.
- Go to the Connected Stage tab at the bottom.
- The list of connected stage can be checked.
- Stage URL: The stage URL is connected.
- Usage Plan: The usage plan information is connected.
Custom domain
Default stage domain is randomly issued in {Region}-{ServiceId}-{StageName}.api.nhncloudservice.com format.
Instead of domains randomly issued as custom domains, users can create domains in {CustomDomainPrefix}.capi.nhncloudservice.com format by specifying the domain's prefix.
Create custom domain
- Go to Custom Domain
- Click Create Custom Domain.
- Custom domain: Enter the prefix of domain that you want to create in custom domain. The entered value is specified in {CustomDomainPrefix} part of {CustomDomainPrefix}.capi.nhncloudservice.com domain.
- GSLB Domain: Enter the GSLB domain to configure API Gateway region redundancy. For more information about API Gateway Region Redundancy Guide, see API Gateway Region Redundancy Guide.
- Click Create button to create a custom domain in {CustomDomainPrefix}.capi.nhncloudservice.com format.
[Note] Custom domain
Custom domain is to be created with strings of at least 2 characters, up to 50 alphanumeric characters, numbers and - characters.
Must be unique across API Gateway services.
Delete custom domain
- Go to Custom Domain
- Select custom domain to delete
- Click the Delete Custom Domain button.
- If clicking on the Delete button, confirmation window for deletion is to be displayed.
- Click the Confirm button on the confirmation window. Deleted data cannot be recovered.
[Note] Unable to delete custom domain
Custom domains connected to stage cannot be deleted.
Please disconnect custom domain in stage and then delete.
Connect stage of custom domain
- Go to stage to connect with custom domain
- Go to stage tab>custom domain tab
- Click the Connect with Stage button in the custom domain you want to connect to.
Disconnect stage from a custom domain
- Go to the stage where you want to disconnect the custom domain.
- Go to stage tab>custom domain tab
- Click the Disconnect from Stage button in the custom domain that you want to disconnect.
[Note] When disconnecting a stage, API cannot be called to a custom domain.
When you disconnect a stage of custom domain, the stage API can no longer be called to the custom domain.
Please make sure that there are no clients calling the API using the custom domain and then disconnect.
API Gateway region redundancy
If the region where the API Gateway is located fails, the API Gateway for that region may not operate normally.
To operate API Gateway service without the impact of a specific region failure, you can avoid it by configuring the API Gateway for multiple regions with redundancy.
The following is a scenario in which API Gateway is newly configured in the existing Korea (Pangyo) Region and the API Gateway is configured in Korea (Pyeongchon) Region to redundancy the Region.
1. Service and Create stage in Korea (Pyeongchon) Region
- Create API Gateway service in Korea (Pangyo) Region.
- Registers the same resources as the Korea (Pangyo) Region Stage in operation with the API Gateway service in Korea (Pyeongchon) Region.
In order to transfer easily, download the resources registered on the stage through Stage > Import Resource as Swagger file, then you can register a resource with the downloaded Swagger file through Resource > Import Resource.
- Create a stage for Korea (Pyeongchon) Region and if there is a stage setting required, modify and deploy the stage.
[Note] Resources > Stage plug-in settings when importing resources.
When importing resources with Swagger file, do not import the plug-ins set on stage. Please add the necessary plug-ins separately in stage setting.
2. Create GSLB
This guide uses the GSLB of NHN Cloud DNS Plus service. For more information on setting up GSLB, refer to DNS Plus Console Usage Guide.
- Go to DNS Plus service
- Create GSLB
- Create health check.
- For Health check path, registered health check resource path by configuring resource method to use for health check in API Gateway in Korea (Pangyo) and Korea (Pyeongchon) Regions.
- A pool that failed health check is excluded from service.
- Create Pool
- For health check in Create Pool, select the health check that you created above.
- For endpoint address, enter API Gateway stage domain for Korea (Pangyo) and Korea (Pyeongchon) Regions.
- For weights and states, set according to redundancy structure (Active, Active-StandBy) that you want to configure.
- Check whether or not the status of the pool connected with the GSLB is ACTIVE.
3. Create custom domain
- Create a custom domain to be used in Korea (Pangyo) and Korea (Pyeongchon) Region when calling Stage API. You have to create a custom domain for each region, and have to create it with the same custom domain.
- When creating a custom domain, enter the GSLB domain that you created in GSLB domain
4. Connect custom domain to stages in each region
- Connect the custom domains you created to each API Gateway stage in Korea (Pangyo) and Korea (Pyeongchon) Region. For more information, refer to Guide to connect Custom Domain with stage.
- Check whether or not the API is successfully called to the custom domain and that traffic is distributed according to GSLB configuration.
API Gateway Service Gateway Integration
Service gateways allow clients and API Gateway to communicate with each other inside NHN Cloud, instead of going through the external internet.
Please refer to the following guide to learn how to integrate API Gateway Service Gateway.
- Create a service gateway for the API Gateway service.
- In the /etc/hosts file, add the service gateway IP and the domain address of the stage you want to access.
- Example: 192.168.1.42 kr1-gateway-example.api.nhncloudservice.com
[Note] Modify the /etc/hosts file
If you don't modify the /etc/hosts file, you won't be able to make API calls to the stage URL.
You can register and use multiple API Gateway stage domains with a single service gateway IP.