Sovereign European Cloud API (SECA) Region API

openapi: 3.2.0
info:
  title: Eu Sovereign Cloud Region API
  version: v1
  description: 'Operations tagged Region across 2 of this provider''s published API definitions: foundation.region.v1.yaml, eu-sovereign-cloud-api-foundation-region-v1-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://demo.secapi.cloud/providers/seca.region
  description: Path Schema
- url: https://region.seca.demo.secapi.cloud
  description: DNS Schema
security:
- bearerAuth: []
tags:
- name: Region
  description: Region management
paths:
  /v1/regions:
    get:
      tags:
      - Region
      security:
      - bearerAuth: []
      summary: List regions
      description: Lists regions and provides paginated, filtered access.
      operationId: listRegions
      parameters:
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/skipTokenParam'
      - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionIterator'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
    servers:
    - url: https://demo.secapi.cloud/providers/seca.region
      description: Path Schema
    - url: https://region.seca.demo.secapi.cloud
      description: DNS Schema
  /v1/regions/{name}:
    get:
      tags:
      - Region
      security:
      - bearerAuth: []
      summary: Get region
      description: 'Get a specific region, useful for polling status updates of resources.

        A `404` response without proper schema has to be ignored and must be

        understood as server being unavailable. Only a response with proper schema

        can be trusted.'
      operationId: getRegion
      parameters:
      - $ref: '#/components/parameters/resourcePathParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Region'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
    servers:
    - url: https://demo.secapi.cloud/providers/seca.region
      description: Path Schema
    - url: https://region.seca.demo.secapi.cloud
      description: DNS Schema
components:
  schemas:
    Region:
      type: object
      description: 'Represents a region, which is a geographical location

        with one or more zones.

        '
      required:
      - spec
      properties:
        metadata:
          $ref: '#/components/schemas/GlobalResourceMetadata'
        spec:
          $ref: '#/components/schemas/RegionSpec'
    Zone:
      type: string
      description: Reference to a specific zone within a region
      minLength: 1
      maxLength: 32
      example: a
    Error403:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: A 403 Forbidden error response
      example:
        status: 403
        type: http://secapi.cloud/errors/forbidden
        title: Forbidden
        detail: The request was valid, but the server is refusing action.
        instance: /errors/403
        sources: []
    NameMetadata:
      type: object
      readOnly: true
      required:
      - name
      description: Metadata for resource names
      properties:
        name:
          type: string
          description: 'Resource identifier in dash-case (kebab-case) format. Must start and end with an alphanumeric character.

            Can contain lowercase letters, numbers, and hyphens. Multiple segments can be joined with dots.

            Each segment follows the same rules.

            '
          minLength: 1
          maxLength: 128
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
          example: resource-name
    PermissionMetadata:
      type: object
      readOnly: true
      description: Metadata for permission management
      required:
      - provider
      - resource
      - verb
      properties:
        provider:
          type: string
          minLength: 1
          maxLength: 64
          example: seca.compute/v1
        resource:
          type: string
          minLength: 1
          maxLength: 256
          example: tenants/tn-1/workspaces/ws-1/instances/my-server
        verb:
          type: string
          minLength: 1
          maxLength: 7
          example: get
      example:
        provider: seca.compute/v1
        resource: tenants/tn-1/workspaces/ws-1/instances/my-server
        verb: get
    Error:
      type: object
      description: 'A detailed error response see https://datatracker.ietf.org/doc/html/rfc7807.

        '
      required:
      - type
      - title
      - status
      - detail
      - instance
      - sources
      properties:
        type:
          type: string
          description: The type of error, expressed as a URI.
          minLength: 1
          maxLength: 4000
          example: https://httpstatuses.io/400
        title:
          type: string
          description: 'A short, human-readable summary of the problem

            type.  It SHOULD NOT change from occurrence to occurrence of the

            problem, except for purposes of localization (e.g., using

            proactive content negotiation; see [RFC7231], Section 3.4).

            '
          minLength: 1
          maxLength: 1024
        status:
          type: number
          description: 'The HTTP status type ([http://secapi.cloud/errors/-rfc7231], Section 6)

            generated by the origin server for this occurrence of the problem.

            '
          minimum: 100
          maximum: 599
          example: 400
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          minLength: 1
          maxLength: 32768
        instance:
          type: string
          description: 'A URI reference that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
          minLength: 1
          maxLength: 256
        sources:
          type: array
          maxItems: 32
          items:
            $ref: '#/components/schemas/ErrorSource'
        meta:
          type: object
          description: A meta object containing non-standard meta-information about the error.
    ResponseMetadata:
      description: 'Metadata for response objects.

        '
      allOf:
      - $ref: '#/components/schemas/PermissionMetadata'
      - type: object
        readOnly: true
        properties:
          skipToken:
            type: string
            description: Opaque cursor to get the next page. Field is omitted when there are no more pages available.
            maxLength: 5
      example:
        skipToken: 'false'
        provider: seca.compute/v1
        resource: tenants/tn-1/workspaces/ws-1/instances/my-server
        verb: get
    Error500:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: A 500 Internal Server Error error response
      example:
        status: 500
        type: http://secapi.cloud/errors/internal-server-error
        title: Internal Server Error
        detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
        instance: /errors/500
        sources: []
    Provider:
      type: object
      description: 'A provider of cloud services

        '
      required:
      - name
      - version
      - url
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          example: seca.network
          x-oapi-codegen-extra-tags:
            x-kubebuilder-validation-min-length: '1'
            x-kubebuilder-validation-max-length: '64'
        version:
          type: string
          minLength: 1
          maxLength: 16
          example: v1
          x-oapi-codegen-extra-tags:
            x-kubebuilder-validation-min-length: '1'
            x-kubebuilder-validation-max-length: '16'
        url:
          type: string
          minLength: 1
          maxLength: 4000
          example: https://demo.secapi.cloud/providers/seca.network
          x-oapi-codegen-extra-tags:
            x-kubebuilder-validation-min-length: '1'
            x-kubebuilder-validation-max-length: '4000'
    Error400:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: A 400 Bad Request error response
      example:
        status: 400
        type: http://secapi.cloud/errors/invalid-request
        title: Bad Request
        detail: The request was invalid or cannot be served.
        instance: /errors/400
        sources: []
    GlobalResourceMetadata:
      description: 'Metadata for global resources with name, permission, modification and type information.

        '
      allOf:
      - $ref: '#/components/schemas/NameMetadata'
      - $ref: '#/components/schemas/PermissionMetadata'
      - $ref: '#/components/schemas/ModificationMetadata'
      - $ref: '#/components/schemas/TypeMetadata'
    Error404:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: A 404 Not Found error response
      example:
        status: 404
        type: http://secapi.cloud/errors/resource-not-found
        title: Not Found
        detail: The requested resource could not be found.
        instance: /errors/404
        sources: []
    ModificationMetadata:
      type: object
      readOnly: true
      description: Base metadata for all resources with optional region references
      required:
      - createdAt
      - lastModifiedAt
      - resourceVersion
      properties:
        createdAt:
          type: string
          format: date-time
          description: Indicates the time when the resource was created. The field is set by the provider and should not be modified by the user.
        deletedAt:
          type: string
          format: date-time
          description: If set, indicates the time when the resource was marked for deletion. Resources with this field set are considered pending deletion.
        lastModifiedAt:
          type: string
          format: date-time
          description: Indicates the time when the resource was created or last modified. Field is used for "If-Unmodified-Since" logic for concurrency control. The provider guarantees that a modification on a single resource can happen only once every millisecond.
        resourceVersion:
          type: integer
          description: Incremented on every modification of the resource. Used for optimistic concurrency control.
          minimum: 1
          format: int64
    ReferenceURN:
      type: string
      minLength: 1
      description: "A unique resource name (URN) used to identify and reference this resource.\n\nThe URN is NOT a URL — it does not contain a protocol scheme (http/https), a host,\nor any endpoint-specific prefix. It is a portable, transport-agnostic identifier.\nA configured SDK client — which knows the provider's base URL and endpoint mapping —\ncan derive a URL from a URN, but the URN alone cannot be turned into a URL without\nthat SDK configuration context. This separation keeps the URN portable across\nenvironments and CSP deployments.\n\nThe full URN format is:\n  `{provider}/{version}/tenants/{tenant}/workspaces/{workspace}/{type}/{name}`\n\nFor hierarchical (nested) resources, additional parent path segments are included:\n  `seca.network/v1/tenants/tn-1/workspaces/ws-1/networks/my-net/route-tables/my-rt`\n\n### Automatic Prefix Inference\n\nIn most cases, the prefix of the URN can be automatically derived in the given context.\nTo simplify usage, only the resource type and name might be specified as a reference\nusing the `<type>/<name>` notation. The suffix can be made more specific by adding\nadditional segments separated by slashes.\n\nThe prefix is automatically inferred from the context. For example, if the resource is a\nblock storage in the same workspace the reference can be specified as\n`block-storages/my-block-storage`. If the resource is a block storage in a different workspace, the\nreference can be specified as `workspaces/ws-1/block-storages/my-block-storage`.\n\nFor automatic prefix inference, the following rules apply:\n- the version is inferred from the current resource version\n- the workspace is inferred from the current workspace\n- the region is inferred from the current region\n- the provider is inferred from the type and context of the usage\n\nThe prefix inference is resolved on admission into the full URN format, which makes it\nmostly suitable for human use.\n"
      maxLength: 255
      example: seca.compute/v1/tenants/tn-1/workspaces/ws-1/instances/my-server
    ErrorSource:
      type: object
      description: An object containing references to the source of the error.
      required:
      - pointer
      - parameter
      properties:
        pointer:
          type: string
          description: A JSON Pointer [RFC6901] to the associated entity in the request document.
          minLength: 1
          maxLength: 256
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
          minLength: 1
          maxLength: 64
    TypeMetadata:
      type: object
      readOnly: true
      required:
      - apiVersion
      - kind
      - ref
      description: 'Metadata for all resources with type information.

        '
      properties:
        apiVersion:
          type: string
          description: API version of the resource
          minLength: 1
          maxLength: 16
          default: v1
        kind:
          type: string
          description: Type of the resource
          enum:
          - activity-log
          - block-storage
          - image
          - instance
          - instance-sku
          - internet-gateway
          - network
          - network-load-balancer
          - network-sku
          - nic
          - object-storage-account
          - public-ip
          - region
          - role
          - role-assignment
          - routing-table
          - security-group
          - security-group-rule
          - storage-sku
          - subnet
          - workspace
          x-enumNames:
          - ResourceKindActivityLog
          - ResourceKindBlockStorage
          - ResourceKindImage
          - ResourceKindInstance
          - ResourceKindInstanceSku
          - ResourceKindInternetGateway
          - ResourceKindNetwork
          - ResourceKindNetworkLoadBalancer
          - ResourceKindNetworkSku
          - ResourceKindNic
          - ResourceKindObjectStorageAccount
          - ResourceKindPublicIP
          - ResourceKindRegion
          - ResourceKindRole
          - ResourceKindRoleAssignment
          - ResourceKindRoutingTable
          - ResourceKindSecurityGroup
          - ResourceKindSecurityGroupRule
          - ResourceKindStorageSku
          - ResourceKindSubnet
          - ResourceKindWorkspace
        ref:
          $ref: '#/components/schemas/ReferenceURN'
    Error401:
      allOf:
      - $ref: '#/components/schemas/Error'
      description: A 401 Unauthorized error response
      example:
        status: 401
        type: http://secapi.cloud/errors/unauthorized
        title: Unauthorized
        detail: Authentication is required and has failed or has not been provided.
        instance: /errors/401
        sources: []
    RegionSpec:
      type: object
      description: 'The specification of a region, including the available zones and providers.

        '
      required:
      - availableZones
      - providers
      properties:
        availableZones:
          description: 'The list of zones available in the region.

            '
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: '#/components/schemas/Zone'
          example:
          - a
          - b
          - c
          x-oapi-codegen-extra-tags:
            x-kubebuilder-validation-items-min-length: '1'
            x-kubebuilder-validation-items-max-length: '32'
            x-kubebuilder-validation-min-items: '1'
            x-kubebuilder-validation-max-items: '32'
        providers:
          description: 'The list of providers available in the region.

            '
          type: array
          minItems: 1
          maxItems: 64
          items:
            $ref: '#/components/schemas/Provider'
          x-oapi-codegen-extra-tags:
            x-kubebuilder-validation-min-items: '1'
            x-kubebuilder-validation-max-items: '64'
    RegionIterator:
      description: Iterator for regions
      type: object
      required:
      - items
      - metadata
      properties:
        items:
          description: List of regions
          type: array
          items:
            $ref: '#/components/schemas/Region'
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
  parameters:
    skipTokenParam:
      in: query
      name: skipToken
      description: Opaque cursor for pagination. Use the skipToken from the previous response to get the next page of results. Note that skipTokens do not guarantee consistency across pages if the underlying data changes between requests
      required: false
      schema:
        type: string
    limitParam:
      in: query
      name: limit
      description: Maximum number of resources to return in the response
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
    resourcePathParam:
      name: name
      in: path
      required: true
      schema:
        type: string
        maxLength: 128
        minLength: 1
        pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
      description: Resource name
    acceptHeader:
      in: header
      name: Accept
      schema:
        type: string
        default: application/json
        example: application/json; deleted=true
        enum:
        - application/json
        - application/json; deleted=true
        - application/json; deleted=only
        x-enumNames:
        - AcceptHeaderJson
        - AcceptHeaderJsonDeletedTrue
        - AcceptHeaderJsonDeletedOnly
      description: 'Controls whether deleted resources are included:

        - `"application/json"`: Returns only non-deleted resources

        - `"application/json; deleted=true"`: Returns both deleted and non-deleted resources

        - `"application/json; deleted=only"`: Returns only deleted resources

        '
    labelSelector:
      in: query
      name: labels
      description: "Filter resources by their labels. Multiple filters are combined with comma.\nFilter syntax:\n  - Equals: key=value\n  - Not equals: key!=value\n  - Wildcards: \\*key\\*=\\*value\\* - substring (contains) match on both key and value. Each `*` can appear at start, end or in the middle to mean \"any characters\". Example: \\*env\\*=\\*prod\\* matches a label key containing \"env\" whose value contains \"prod\".\n  - Numeric: key>value, key<value, key>=value, key<=value\n  - Namespaced key examples: 'monitoring:alert-level=high' or 'billing:team=platform'\n"
      required: false
      schema:
        type: string
        example: cloud:region=us-east-1,billing:team=platform,tier!=dev
  responses:
    Error400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400'
          example:
            status: 400
            type: http://secapi.cloud/errors/invalid-request
            title: Bad Request
            detail: The request was invalid or cannot be served.
            instance: /errors/400
            sources: []
    Error401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401'
          example:
            status: 401
            type: http://secapi.cloud/errors/unauthorized
            title: Unauthorized
            detail: Authentication is required and has failed or has not been provided.
            instance: /errors/401
            sources: []
    Error500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error500'
          example:
            status: 500
            type: http://secapi.cloud/errors/internal-server-error
            title: Internal Server Error
            detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
            instance: /errors/500
            sources: []
    Error404:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404'
          example:
            status: 404
            type: http://secapi.cloud/errors/resource-not-found
            title: Not Found
            detail: The requested resource could not be found.
            instance: /errors/404
            sources: []
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403'
          example:
            status: 403
            type: http://secapi.cloud/errors/forbidden
            title: Forbidden
            detail: The request was valid, but the server is refusing action.
            instance: /errors/403
            sources: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Use a JWT token for authentication. The token identifies the user,

        and policies (RBAC, ABAC, or hybrid) determine authorization.

        '
x-refined-from:
- foundation.region.v1.yaml
- eu-sovereign-cloud-api-foundation-region-v1-openapi.yml