Help Center/ ROMA Connect/ User Guide/ Service Integration Guide (Old Edition)/ Managing APIs/ Appendix: Extended Swagger Definition of APIs

Updated on 2024-11-27 GMT+08:00

View PDF

Appendix: Extended Swagger Definition of APIs

On the basis of the basic Swagger definition, ROMA Connect defines the extended definition of APIs, such as the authentication mode and backend service definition. This section describes the extended definitions of APIs.

1: x-apigateway-auth-type

Meaning: Swagger-based apiKey authentication format, which defines an authentication mode provided by ROMA Connect.

Scope of effect: Security Scheme Object

Example

securityDefinitions:
  customize-name-iam:
    type: "apiKey"
    name: "unused"
    in: "header"
    x-apigateway-auth-type: "IAM"
  customize-name-app:
    type: "apiKey"
    name: "Authorization"
    in: "header"
    x-apigateway-auth-type: "AppSigv1"
  customize-name-iam-none:
    type: "apiKey"
    name: "unused"
    in: "header"
    x-apigateway-auth-type: "IAM_NONE"

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Authentication type. Only apiKey is supported.
name	Yes	String	Name of the parameter for authentication. When x-apigateway-auth-type is set to AppSigv1, set name to Authorization. When x-apigateway-auth-type is set to IAM or IAM_NONE, set name to unused.
in	Yes	String	Location of the parameter. Only header is supported.
description	No	String	Description of the parameter.
x-apigateway-auth-type	Yes	String	APIC authentication mode. AppSigv1, IAM, and IAM_NONE are supported.

2: x-apigateway-request-type

Meaning: API request type, which can be public or private.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-request-type: 'public'

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-request-type	Yes	String	API visibility. The options include public and private. public: The API can be made available for sale. private: The API will not be available for sale.

3: x-apigateway-match-mode

Meaning: Request URL matching mode, which can be NORMAL or SWA.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-match-mode: 'SWA'

**Table 3** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-match-mode	Yes	String	Matching mode of the API request path. The value can be SWA or NORMAL. SWA: prefix match. For example, if the request path is set to /test/AA and the matching mode is set to SWA, the API can be accessed using /test/AA/BB or /test/AA/CC but cannot be accessed using /test/AACC. NORMAL: exact match.

4: x-apigateway-cors

Meaning: Specifies whether APIs defined by ROMA Connect support CORS.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-cors: true

**Table 4** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-cors	No	Boolean	Whether CORS is supported.

For the API request for enabling CORS, the headers listed in the following table will be added to the response.

Parameter Name	Parameter Value	Description
Access-Control-Max-Age	172800	Maximum time the response of a preflight request can be cached.
Access-Control-Allow-Origin	*	Domain that can be accessed. The asterisk (*) indicates that requests from any domain are allowed.
Access-Control-Allow-Headers	X-Sdk-Date, X-Sdk-Nonce, X-Proxy-Signed-Headers, X-Sdk-Content-Sha256, X-Forwarded-For, Authorization, Content-Type, Accept, Accept-Ranges, Cache-Control, Range	Header information fields that can be used in API requests.
Access-Control-Allow-Methods	GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH	HTTP methods allowed by the API request.

5: x-apigateway-any-method

Meaning: API request method used by default if no HTTP request method is specified.

Scope of effect: Path Item Object

Example

paths:
  '/path':
    get:
      produces:
        - application/json
      responses:
        "200":
          description: "get response"
    x-apigateway-any-method:
      produces:
        - application/json
      responses:
        "200":
          description: "any response"

6: x-apigateway-backend

Meaning: API backend definition.

Scope of effect: Operation Object

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"

**Table 5** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Backend service type. HTTP, HTTP-VPC, and MOCK are supported.
parameters	No	x-apigateway-backend.parameters	Backend parameters.
httpEndpoints	No	x-apigateway-backend.httpEndpoints	HTTP backend service definition.
httpVpcEndpoints	No	x-apigateway-backend.httpVpcEndpoints	HTTP-VPC backend service definition.
functionEndpoints	No	x-apigateway-backend.functionEndpoints	Function backend service definition.
mockEndpoints	No	x-apigateway-backend.mockEndpoints	Mock backend service definition.

6.1: x-apigateway-backend.parameters

Meaning: API backend definition.

Scope of effect: x-apigateway-backend

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "authorization token"
          type: "string"
          in: "header"
          required: true
        - name: "userId"
          description: "user name"
          type: "string"
          in: "path"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        parameters:
          - name: "userId"
            value: "userId"
            in: "query"
            origin: "REQUEST"
            description: "user name"
          - name: "X-Invoke-User"
            value: "apigateway"
            in: "header"
            origin: "CONSTANT"
            description: "invoke user"

**Table 6** Parameter description
Parameter	Mandatory	Type	Description
name	Yes	String	Parameter name, which consists of a maximum of 32 bytes, starting with a letter. Only letters, digits, periods (.), hyphens (-), and underscores (_) are allowed. The names of header parameters are not case-sensitive.
value	Yes	String	Parameter value, which is a parameter name if the parameter comes from a request.
in	Yes	String	Parameter location, which can be header, query, or path.
origin	Yes	String	Parameter mapping source. REQUEST and CONSTANT are supported.
description	No	String	Parameter description.

6.2: x-apigateway-backend.httpEndpoints

Meaning: HTTP backend service definition.

Scope of effect: x-apigateway-backend

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "authorization token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        httpEndpoints:
          address: "www.example.com"
          scheme: "http"
          method: "GET"
          path: "/users"
          retryCount: "3"
          timeout: 30000

**Table 7** Parameter description
Parameter	Mandatory	Type	Description
address	Yes	Array	Backend service address. The format is <Domain name or IP address>:[Port number]
scheme	Yes	String	Backend request protocol. HTTP and HTTPS are supported.
method	Yes	String	Backend request method. GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY are supported.
path	Yes	String	Backend request path, which can contain variables.
retryCount	No	String	Number of retry times upon a backend failure.
timeout	No	Number	Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.

6.3: x-apigateway-backend.httpVpcEndpoints

Meaning: HTTP-VPC backend service definition.

Scope of effect: x-apigateway-backend

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "authorization token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP-VPC"
        httpVpcEndpoints:
          name: "vpc-test-1"
          scheme: "http"
          method: "GET"
          path: "/users"
          timeout: 30000

**Table 8** Parameter description
Parameter	Mandatory	Type	Description
name	Yes	Array	VPC channel name.
scheme	Yes	String	Backend request protocol. HTTP and HTTPS are supported.
method	Yes	String	Backend request method. GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY are supported.
path	Yes	String	Backend request path, which can contain variables.
timeout	No	Number	Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.

6.4: x-apigateway-backend.functionEndpoints

Meaning: FUNCTION backend service definition.

Scope of effect: x-apigateway-backend

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "authorization token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "FUNCTION"
        functionEndpoints:
          version: "v1"
          function-urn: ""
          invocation-type: "synchronous"
          timeout: 30000

**Table 9** Parameter description
Parameter	Mandatory	Type	Description
function-urn	Yes	String	Function URN.
version	Yes	String	Function version.
invocation-type	Yes	String	Function invocation type. async or sync are supported.
timeout	No	Number	Function timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.

6.5: x-apigateway-backend.mockEndpoints

Meaning: Mock backend service definition.

Scope of effect: x-apigateway-backend

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "authorization token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "MOCK"
        mockEndpoints:
          result-content: "mocked"

**Table 10** Parameter description
Parameter	Mandatory	Type	Description
result-content	Yes	String	Mock response.

7: x-apigateway-backend-policies

Meaning: API backend policy.

Scope of effect: Operation Object

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"

**Table 11** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Backend service type. HTTP, HTTP-VPC, and MOCK are supported.
name	Yes	String	Name
parameters	No	x-apigateway-backend.parameters	Backend parameters.
httpEndpoints	No	x-apigateway-backend.httpEndpoints	HTTP service definition.
httpVpcEndpoints	No	x-apigateway-backend.httpVpcEndpoints	HTTP-VPC service definition.
functionEndpoints	No	x-apigateway-backend.functionEndpoints	Function service definition.
mockEndpoints	No	x-apigateway-backend.mockEndpoints	Mock service definition.
conditions	Yes	x-apigateway-backend-policies.conditions	Backend policy condition.

7.1: x-apigateway-backend-policies.conditions

Meaning: API backend policy.

Scope of effect: x-apigateway-backend-policies

Example

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"

**Table 12** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Policy condition type. equal, enum, and pattern are supported.
value	Yes	String	Policy condition value.
origin	Yes	String	Policy condition source. source and request are supported.
parameter	No	String	Input parameter name if the origin parameter is set to request.

8: x-apigateway-ratelimit

Meaning: Request throttling policy.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-ratelimit: 'customRatelimitName'

**Table 13** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-ratelimit	No	String	Name of the referenced request throttling policy. Set this parameter to customRatelimitName.

9: x-apigateway-ratelimits

Meaning: Mapping between a request throttling policy name and limit values.

Scope of effect: Swagger Object

Example

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: second/minute/hour
    shared: true
    special: 
      - type: APP
        limit: 100
        instance: xxxxxxxxx

**Table 14** Parameter description
Parameter	Mandatory	Type	Description
customRatelimitName	No	x-apigateway-ratelimits.policy	Custom request throttling policy. To use a request throttling policy, set x-apigateway-ratelimit to the name of the policy.

9.1: x-apigateway-ratelimits.policy

Meaning: Definition of a request throttling policy.

Scope of effect: x-apigateway-ratelimits

Example

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxx

**Table 15** Parameter description
Parameter	Mandatory	Type	Description
api-limit	Yes	Number	Maximum number of times an API can be called.
user-limit	No	Number	Number of times the API can be called by a user.
app-limit	No	Number	Number of times the API can be called by an app.
ip-limit	No	Number	Number of times the API can be called by an IP address.
interval	Yes	Number	Throttling period.
unit	Yes	String	Throttling unit, which can be SECOND, MINUTE, HOUR, or DAY.
shared	No	Boolean	Whether to share the throttling limits among APIs.
special	No	x-apigateway-ratelimits.policy.special	Special request throttling policy.

9.2: x-apigateway-ratelimits.policy.special

Meaning: Definition of a special request throttling policy.

Scope of effect: x-apigateway-ratelimits.policy

Example

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxxx

**Table 16** Parameter description
Parameter	Mandatory	Type	Description
type	Yes	String	Excluded request throttling type, which can be APP or USER.
limit	Yes	Number	Access limit.
instance	Yes	String	Excluded app or user

10: x-apigateway-access-control

Meaning: Access control policy.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-access-control: 'customAccessControlName'

**Table 17** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-access-control	No	String	Name of the referenced access control policy. Set this parameter to customAccessControlName.

11: x-apigateway-access-controls

Meaning: Mapping between an access control policy name and limit settings.

Scope of effect: Swagger Object

Example

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16

**Table 18** Parameter description
Parameter	Mandatory	Type	Description
customAccessControlName	No	x-apigateway-access-controls.policy	Custom access control policy. To use an access control policy, set x-apigateway-access-control to the name of the policy.

11.1: x-apigateway-access-controls.policy

Meaning: Definition of an access control policy.

Scope of effect: x-apigateway-access-controls

Example

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16

**Table 19** Parameter description
Parameter	Mandatory	Type	Description
acl-type	Yes	String	Access control effect. The options include PERMIT and DENY.
entity-type	Yes	String	Access control object. Only IP addresses are supported.
value	Yes	String	Access control policy values. Use commas (,) to separate multiple values.

12: x-apigateway-roma-app

Meaning: Integration application bound to the API.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      x-apigateway-roma-app: 'romaAppName'

**Table 20** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-roma-app	Yes	String	Name of the integration application bound to the API.

13 x-apigateway-plugins

Meaning: API plug-in service.

Scope of effect: Operation Object

Example:

paths:
  '/path':
    get:
      x-apigateway-plugins: ['Plugin_mock']

**Table 21** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-plugins	No	Array	List of plug-ins bound to the API.

14 x-apigateway-is-send-fg-body-base64

Meaning: Whether to perform Base64 encoding on the request body used for interaction with FunctionGraph. The value is of the Boolean type.

Scope of effect: Operation Object

Example

paths:
  '/path':
    get:
      "x-apigateway-is-send-fg-body-base64": true

**Table 22** Parameter description
Parameter	Mandatory	Type	Description
x-apigateway-is-send-fg-body-base64	No	boolean	Specifies whether to perform Base64 encoding on the request body for interaction with FunctionGraph. true: yes false: no