API YAML Definition with Upstream Definition and Main/Sandbox Upstreams

[renuka-fernando]

Suggested API YAML

version: api-platform.wso2.com/v1alpha1 # Suggestion 1: Change the version
kind: HttpRestApi # Suggestion 9: New name fo the kind
metadata: # Suggestion 2: Move name and version to metadata section
  name: weather-api # Suggestion 11: # name is the identifier.
spec:
  displayName: Weather API # Suggestion 12: in CLI and UI: displayName is shown as the name.
  version: v1.0 # Suggestion 10: Move API version here
  context: /weather
  upstreamDefinitions: # Suggestion 3: Define upstreams with names. This is for advance usacase.
    - name: my-upstream-1
      loadBalancer:
        strategy: ROUND_ROBIN
      timeout:
        connect: 5s
        request: 30s
        idle: 60s
      retry:
        attempts: 3
        conditions: [5xx, timeout, connection-failure]
        backoff: exponential
      upstreams: # Multiple upstreams
        - urls:
            - http://prod-backend-1:5000/api/v2
          weight: 80
        - urls:
            - http://sandbox-backend-1:5000/api/v2
          weight: 20
  upstream: # API Level upstream
    main: # Suggestion 4: Changed to single URL. If multiple URLs are needed, use upstreamDefinitions.
      url: http://prod-backend:5000/api/v2 # Suggestion 5: Use one of "url" or "ref"
    sandbox:
      ref: my-upstream-1
  gatewayHost: # Suggestion 7: Define gateway hosts
    main: api.example.com
    sandbox: sandbox-api.example.com
  operations:
    - method: GET
      path: /{country_code}/{city}
      upstream: # Operational Level upstream
        main:
          url: http://prod-backend:5000/api/v2
        sandbox:
          ref: my-upstream-1
      policies:
        - name: ModifyHeaders
          version: v1.0.0
          enabled: true
          params:
            requestHeaders:
              - action: SET
                name: operation-level-req-header
                value: hello
            responseHeaders:
              - action: SET
                name: operation-level-res-header
                value: world
    - method: POST
      path: /{country_code}/{city}
    - method: PUT|PATCH # Suggestion 6: Support for multiple methods in single operation
      path: /{country_code}/{city}

Gateway Config

gateway_host: # Suggestion 8: Gateway host config for main and sandbox
  main: "*.wso2.com"
  sandbox: "*sand.wso2.com"

Suggestions Summary

1. Change the version to a more specific one like api-platform.wso2.com/v1alpha1 to indicate it's part of a specific API platform.
2. Move name and version under a metadata section to better organize
3. Define upstreams with names under upstreamDefinitions for better reusability and advanced configurations.
4. Changed to single URL under upstream for simplicity. If multiple URLs are needed, use upstreamDefinitions.
5. Use one of url or ref under upstreams.
6. Support for multiple methods in a single operation using |
7. Define gateway hosts for main and sandbox environments.
8. Define gateway hosts for main and sandbox environments in the gateway configuration.
9. Use a k8s friendly kind name like HttpRestApi.
10. Move API version under spec since in k8s CRDs, version is usually part of the spec.
11. Use name as the identifier in metadata.
12. Use displayName for showing the name in CLI and UI.

[BLasan]

Is this a customized one that we're going to maintain in the gateway? Or are we going to accept standard openapi specification in the spec section? If so, we need to bring this structure for the other API types as well

[malinthaprasan]

Is this a customized one that we're going to maintain in the gateway? Or are we going to accept standard openapi specification in the spec section? If so, we need to bring this structure for the other API types as well

This is a custom spec. And yes other API types have to match whenever it is possible but its not mandatory (we should write the spec according the to API type and the expected experience. eg: we don't need to have "operations" in MCPs, it can use "tools"). Based on the kind (eg: type/http) different API types can use entirely different specs.

[nimsara66]

How do we handle backend security in a multiple-upstream configuration?

For example:

upstreams:
  # First upstream
  - urls:
      - http://prod-backend-1:5000/api/v2
    weight: 80

  # Second upstream
  - urls:
      - http://sandbox-backend-1:5000/api/v2
    weight: 20

[malinthaprasan]

Suggestion for sandbox and main vhosts:

version: api-platform.wso2.com/v1alpha1
kind: http/rest
metadata:
  name: Weather-API
  version: v1.0
spec:
  context: /weather
  vhosts:  # Optional
    main: api.weather.com # Optional - if not configured, default vhost config is used
    sandbox: sandbox-api.weather.com # Optional - if not configured, API will not be deployed with the sandbox vhost (sandbox endpoint can't be accessed)
  upstreamDefinitions: # Suggestion 3: Define upstreams with names. This is for advance usacase.
    - name: my-upstream-1
      loadBalancer:
        strategy: ROUND_ROBIN
      timeout:
        connect: 5s
        request: 30s
        idle: 60s
      retry:
        attempts: 3
        conditions: [5xx, timeout, connection-failure]
        backoff: exponential
      upstreams: # Multiple upstreams
        - urls:
            - http://prod-backend-1:5000/api/v2
          weight: 80
        - urls:
            - http://sandbox-backend-1:5000/api/v2
          weight: 20
  upstream: # API Level upstream

[renuka-fernando]

Discussion notes

Attendees: Pubudu Gunatilaka, Thivindu Paranayapa, Nimsara Fernando, Nuwan Dias, Rakhitha Ranathunge, Piyumal Kularathna, Tharsanan Kurukulasingam, Thenujan Nagaratnam, Arshardh Ifthikar, Renuka Fernando, Osura Viduranga, Malintha Amarasinghe

Notes:

• Go with the same API YAML as a K8s CR.

New changes:

version: api-platform.wso2.com/v1alpha1 # Suggestion 1: Change the version
kind: HttpRestApi
metadata: # Suggestion 2: Move name and version to metadata section
 name: weather-api # name is the identifier.
spec:
 version: v1.0.0
 displayName: Weather API # in CLI and UI: displayName is shown as the name.
 context: /weather

Updated the suggested API YAML here #369 (comment).

[BLasan]

There's a problem with the existing definition. We may need to bring the kind or duplicate the field in spec to accept only http/rest and async/websub definitions[1]. Current implementation is done around this approach. We need to finalize whether we are accepting any spec and validate against the kind internally.

One possible solution is maintaining the accepted Async and HTTP data as structs and try to parse the spec we received based on the kind. If there's a validation error then we can reject the request at the earliest or proceed otherwise. When finalizing the openapi for the gateway-controller, please consider the async apis as well as the gateway is not going to support only HTTP

@malinthaprasan @renuka-fernando FYI

[1] https://swagger.io/docs/specification/v3_0/data-models/inheritance-and-polymorphism/

[Tharsanan1]

Discussion notes

With a discussion with Malintha and Renuka we decided to change the kind and apiVersion as follows

version: gateway.api-platform.wso2.com/v1alpha1 # Suggestion 1: Change the version
kind: RestApi
metadata: # Suggestion 2: Move name and version to metadata section
 name: weather-api # name is the identifier.
spec:
 version: v1.0.0
 displayName: Weather API # in CLI and UI: displayName is shown as the name.
 context: /weather

[nimsara66]

Discussion notes

spec:
  displayName: Weather API # Suggestion 12: in CLI and UI: displayName is shown as the name.
  version: v1.0 # Suggestion 10: Move API version here
  context: /weather
  upstreamDefinitions: # Suggestion 3: Define upstreams with names. This is for advance usacase.
    - name: my-upstream-1
      loadBalancer:
        strategy: ROUND_ROBIN
      timeout:
        connect: 5s
        request: 30s
        idle: 60s
      retry:
        attempts: 3
        conditions: [5xx, timeout, connection-failure]
        backoff: exponential
      upstreams: # Multiple upstreams
        - url: http://prod-backend-1:5000/api/v2
          weight: 80
        - url: http://sandbox-backend-1:5000/api/v2
           weight: 20
  upstream: # API Level upstream
    main: # Suggestion 4: Changed to single URL. If multiple URLs are needed, use upstreamDefinitions.
      url: http://prod-backend:5000/api/v2 # Suggestion 5: Use one of "url" or "ref"
    sandbox:
      ref: my-upstream-1
  vhosts:
    main:
      default: "*"
    sandbox:
      default: "sandbox-*"
  operations:

Default Gateway Config

• Validation only for deployment
• Only for governance purposes

gateway_host: # Suggestion 8: Gateway host config for main and sandbox
  main: "*"
  sandbox: "sand-*"

[malinthaprasan]

When nothing is specified in GW config:

gatewayConfig:
  vhosts:
    main
       default: "*"
    sandbox:
       default: "sandbox-*"

When there's only one vhost:

gatewayConfig:
  vhosts:
    main
       default: "*.wso2.com"
    sandbox:
       default: "sandbox-*.wso2.com"

When there are multiple vhosts:

gatewayConfig:
  vhosts:
    main
       domains: 
          - *.wso2.com
          - *.foo.com
       default: "*.wso2.com"
    sandbox:
       domains: 
          - sandbox-*.wso2.com
          - sandbox-*.foo.com
       default: "sandbox-*.wso2.com"

default vhost in gateway config will be used when vhost is not specified in api.yaml.