Control Node OpenAPI documentation

[davide-baldo]

This PR properly documents Control Node OpenAPI schema, and also makes some adjustments to better reflect usual restful conventions.

To generate and view the OpenAPI documentation, you can run:

cargo run --bin=node_control_api_schema > schema.yaml && npx @redocly/cli build-docs schema.yaml && open redoc-static.html

The current schema is:

openapi: 
info:
  title: Ockam Node Control API
  description: |2

    ## Overview
    This API is designed to control Ockam nodes via HTTP requests without having to use Ockam Command or Ockam library.
    You can expect a similar abstraction level as Ockam Command, but with a more programmatic approach.

    The endpoint will receive the HTTP request and forward it to the selected node using the `node`
    parameter. How the node will be selected starting from the name is configuration dependent.

    ## Versioning
    Current major `0.Y.Z` is considered unstable and may have breaking changes.
    Future versions will follow semantic versioning, breaking changes will be reflected in the major version number.

    ## Authentication
    Only a simple bearer token is required to authenticate. The token is passed in the `Authorization`
    header: `Authorization: Bearer my-secret-token`.

    ## Development
    The easiest way to get development started is to use this API with the Ockam Command and run a single node acting both as a frontend and backend.
    ```sh
    ockam node create --foreground -vv --launch-configuration '{
      "start_default_services": true,
      "startup_services": {
        "control_api": {
          "authentication_token": "my-secret-token",
          "backend": true,
          "frontend": true,
          "http_bind_address": "127.0.0.1:8080"
        }
      }
    }'
    ```

    When an undocumented error is returned, such as internal server error, a message contained by `ErrorResponse` is usually present for debugging purposes.
    It's highly recommended to check the logs of the Ockam nodes for more information.
  contact:
    name: Ockam Developers
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 0.1.0
paths:
  /{node}/authority-members:
    get:
      tags:
      - Authority Members
      summary: List Authority Members
      description: List all members of the Authority.
      operationId: list_authority_members
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Optional list request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListAuthorityMembersRequest'
        required: true
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorityMember'
        '404':
          description: Specified project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/authority-members/{member}:
    get:
      tags:
      - Authority Members
      summary: Get Authority Member
      description: Get the specified member of the Authority by identity.
      operationId: get_authority_member
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: member
        in: path
        description: Member identity
        required: true
        schema:
          type: string
        example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
      requestBody:
        description: Optional get member request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAuthorityMemberRequest'
        required: true
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityMember'
        '404':
          description: Specified project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Authority Members
      summary: Add or update an Authority Member
      description: |-
        Add or update an Authority Member with the specified attributes.
        Attributes will overwrite the existing ones if the member already exists.
      operationId: add_or_update_authority_member
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: member
        in: path
        description: Member identity
        required: true
        schema:
          type: string
        example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
      requestBody:
        description: Creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOrUpdateAuthorityMemberRequest'
        required: true
      responses:
        '201':
          description: Successfully created
        '404':
          description: Specified project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Authority Members
      summary: Remove an Authority Member
      description: Remove the specified member of the Authority by identity.
      operationId: remove_authority_member
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: member
        in: path
        description: Member identity
        required: true
        schema:
          type: string
        example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
      requestBody:
        description: Optional remove member request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveAuthorityMemberRequest'
        required: true
      responses:
        '200':
          description: Successfully removed
        '404':
          description: Specified project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/relays:
    get:
      tags:
      - Relays
      summary: List all Relays
      description: List all Relays created in the node regardless of their status.
      operationId: list_relay
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      responses:
        '200':
          description: Successfully listed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RelayStatus'
    post:
      tags:
      - Relays
      summary: Create a new Relay
      description: |-
        Create a new Relay, the main parameters are the destination node `to` and the `name`.
        The address inherits the name value, but it's possible to specify it to allow the creation
        of multiple relays with the same address to different nodes.
        The creation will be asynchronous and the initial status will be `down`.
        Note that a specific `ockam-relay` attribute is required to allow the relay creation in the
        destination node.
      operationId: create_relay
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRelayRequest'
        required: true
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayStatus'
  /{node}/relays/{relay_name}:
    get:
      tags:
      - Relays
      summary: Get a Relay
      description: Get the specified Relay by name.
      operationId: get_relay
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: relay_name
        in: path
        description: Relay name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayStatus'
        '404':
          description: Relay not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Relays
      summary: Delete a Relay
      description: Delete the specified Relay by name.
      operationId: delete_relay
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: relay_name
        in: path
        description: Relay name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted
  /{node}/tcp-inlets:
    get:
      tags:
      - Portals
      summary: List all TCP Inlets
      description: List all TCP Inlets created in the node regardless of their status.
      operationId: list_tcp_inlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      responses:
        '200':
          description: Successfully listed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InletStatus'
    post:
      tags:
      - Portals
      summary: Create a new TCP Inlet
      description: |-
        Create a TCP Inlet, the main parameters are the destination `to`, and the bind address `from`.
        You can also choose to the listen with a valid TLS certificate, restrict access to the Inlet with
        `authorized` and `allow`, and select a specialized Portals with `kind`.
        The creation will be asynchronous and the initial status will be `down`.
      operationId: create_tcp_inlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInletRequest'
        required: true
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InletStatus'
  /{node}/tcp-inlets/{tcp_inlet_name}:
    get:
      tags:
      - Portals
      summary: Get a TCP Inlet
      description: Get the specified TCP Inlet by name
      operationId: get_tcp_inlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_inlet_name
        in: path
        description: TCP Inlet name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InletStatus'
        '404':
          description: TCP Inlet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Portals
      summary: Delete a TCP Inlet
      description: Delete the specified TCP Inlet by name.
      operationId: delete_tcp_inlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_inlet_name
        in: path
        description: TCP Inlet name
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted
    patch:
      tags:
      - Portals
      summary: Update a TCP Inlet
      description: |-
        Update the specified TCP Inlet by name.
        Currently only `allow` policy expression can be updated, for more advanced updates it's necessary
        to delete the TCP Inlet and create a new one.
      operationId: update_tcp_inlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_inlet_name
        in: path
        description: TCP Inlet name
        required: true
        schema:
          type: string
      requestBody:
        description: Update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInletRequest'
        required: true
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InletStatus'
        '404':
          description: TCP Inlet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/tcp-outlets:
    get:
      tags:
      - Portals
      summary: List all TCP Outlets
      description: List all TCP Outlets created in the node.
      operationId: list_tcp_outlets
      parameters:
      - name: node
        in: path
        description: Destination node name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully listed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OutletStatus'
    post:
      tags:
      - Portals
      summary: Create a TCP Outlet
      description: |-
        Create a new TCP Outlet, the main parameter are the destination `to`, and the worker address
        `address` which is used to identify the outlet within the node.
        The `kind` parameter can be used to create a special outlet, and the `tls` parameter can be used to
        connect to TLS endpoints.
        The creation will be synchronous, without any blocking operation.
      operationId: create_tcp_outlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOutletRequest'
        required: true
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutletStatus'
        '409':
          description: Already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/tcp-outlets/{tcp_outlet_address}:
    get:
      tags:
      - Portals
      summary: Get a TCP Outlet
      description: Get the specified TCP Outlet by address.
      operationId: get_tcp_outlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_outlet_address
        in: path
        description: TCP Outlet address
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutletStatus'
        '404':
          description: TCP Outlet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Portals
      summary: Delete a TCP Outlet
      description: Delete the specified TCP Outlet by address.
      operationId: delete_tcp_outlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_outlet_address
        in: path
        description: TCP Outlet address
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted
        '404':
          description: TCP Outlet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Portals
      summary: Update a TCP Outlet
      description: |-
        Update the specified TCP Outlet by address.
        Currently only `allow` policy expression can be updated, for more advanced updates it's necessary
        to delete the TCP Outlet and create a new one.
      operationId: update_tcp_outlet
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      - name: tcp_outlet_address
        in: path
        description: TCP Outlet address
        required: true
        schema:
          type: string
      requestBody:
        description: Update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOutletRequest'
        required: true
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutletStatus'
        '404':
          description: TCP Outlet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/tickets:
    post:
      tags:
      - Tickets
      summary: Create a new Ticket
      description: |-
        Create a new Ticket, the main parameters are `attributes`, the list of attributes associated
        with the ticket, and `project`, the target project for the ticket. In the vast majority of cases,
        specifying the project name will be enough, but it's also possible to specify a custom Ockam
        Authority and a custom node acting as a Project.
        You can also limit the validity of the ticket by specifying the `usage_count` and `expires_in`
        fields.
        The ticket is returned as an opaque string that can be used to enroll to a project, either via API
        or via CLI with the `ockam project enroll` command.
      operationId: create_ticket
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Create Ticket request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTicketRequest'
        required: true
      responses:
        '201':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '404':
          description: Specified project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{node}/tickets/enroll:
    post:
      tags:
      - Tickets
      summary: Enroll to a Project using a Ticket
      description: |-
        This API enroll a node to a Project using the provided Ticket.
        Note that this API imports the Project in the node database, but the node won't be able to use
        it until it restarts.
        The easiest way to use a ticket is to specify the ticket directly during the node creation.
      operationId: project_enroll
      parameters:
      - name: node
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/NodeName'
      requestBody:
        description: Project enrollment request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollProjectRequest'
        required: true
      responses:
        '200':
          description: The node was already enrolled, no change in state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityInformation'
        '201':
          description: Successfully enrolled, new credential can be used right away
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityInformation'
        '202':
          description: Enrolled, but the node needs a restart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityInformation'
components:
  schemas:
    AddOrUpdateAuthorityMemberRequest:
      type: object
      required:
      - attributes
      properties:
        attributes:
          $ref: '#/components/schemas/Attributes'
        authority:
          oneOf:
          - $ref: '#/components/schemas/Authority'
            description: Authority to use when creating the ticket;
          default:
            project:
              name: null
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to use when contacting the Authority node;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
    Attributes:
      type: object
      description: |2

        Credential attributes.
        Attributes are key-value pairs that can be used to describe a credential.
        Ockam uses `ockam-` as a prefix for its own attributes.
        [You can learn more about attributes in the Ockam documentation](https://docs.ockam.io/reference/protocols/access-controls)
      additionalProperties:
        type: string
      propertyNames:
        type: string
      example:
        my-attribute: my-value
        ockam-relay: relay-name
        ockam-role: member
    Authority:
      oneOf:
      - type: object
        required:
        - project
        properties:
          project:
            type: object
            properties:
              name:
                type:
                - string
                - 'null'
                description: |-
                  Name of the project
                  When omitted, the default project will be used
      - type: object
        required:
        - provided
        properties:
          provided:
            type: object
            required:
            - route
            - identity
            properties:
              identity:
                type: string
                description: Identifier of the authority node
                example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
              route:
                type: string
                description: |-
                  Multiaddress to the node that will be used as an authority;
                  When omitted, the default node will be used
                example: /dnsaddr/my-authority.example.com/tcp/4001/secure/api
    AuthorityInformation:
      type: object
      required:
      - route
      - identity
      - address
      properties:
        address:
          $ref: '#/components/schemas/HostnamePort'
          description: Hostname and port of the authority node
        identity:
          type: string
          description: Identity of the authority node
        route:
          type: string
          description: Route to the authority node
    AuthorityMember:
      type: object
      required:
      - identity
      - attributes
      properties:
        attributes:
          $ref: '#/components/schemas/Attributes'
        identity:
          type: string
          description: Member identity
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
    ConnectionStatus:
      type: string
      enum:
      - up
      - down
    CreateInletRequest:
      type: object
      required:
      - to
      properties:
        allow:
          type:
          - string
          - 'null'
          description: |-
            Policy expression that will be used for access control to the TCP Inlet;
            When omitted, the policy set for the "tcp-inlet" resource type will be used.
            [Learn more about Policies expression on the Ockam documentation](https://docs.ockam.io/reference/protocols/access-controls).
        authorized:
          type:
          - string
          - 'null'
          description: |-
            Restrict access to the TCP Inlet to the provided identity;
            When omitted, all identities are allowed;
          example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
        from:
          oneOf:
          - $ref: '#/components/schemas/HostnamePort'
            description: Bind address for the TCP Inlet
          default:
            hostname: 127.0.0.1
            port: 0
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to be used to create the secure channel;
            When omitted, the node's identity will be used
        kind:
          $ref: '#/components/schemas/InletKind'
          description: Kind of the Portal
        name:
          type:
          - string
          - 'null'
          description: |-
            Name of the TCP Inlet;
            Whe omitted, a random name will be generated
        retry-wait:
          type: integer
          format: int64
          description: |-
            When connection is lost, how long to wait before retrying to connect to the TCP Outlet;
            In milliseconds;
          default: 20000
          minimum: 0
        tls:
          oneOf:
          - $ref: '#/components/schemas/InletTls'
            description: TLS Inlet implementation
          default: none
        to:
          type: string
          description: Multiaddress to a TCP Outlet
          example: /project/default/service/forward_to_node1/secure/api/service/outlet
    CreateOutletRequest:
      type: object
      required:
      - kind
      - to
      properties:
        address:
          type:
          - string
          - 'null'
          description: The address of the outlet, also acts as an identifier for the resource
        allow:
          type:
          - string
          - 'null'
          description: |-
            Policy expression that will be used for access control to the TCP Outlet;
            by default, the policy set for the "tcp-outlet" resource type will be used.
            [Learn more about Policies expression on the Ockam documentation](https://docs.ockam.io/reference/protocols/access-controls).
        kind:
          $ref: '#/components/schemas/OutletKind'
          description: The kind of the outlet
        tls:
          oneOf:
          - $ref: '#/components/schemas/OutletTls'
            description: The TLS configuration for the outlet
          default: None
        to:
          $ref: '#/components/schemas/HostnamePort'
          description: The destination address of the TCP connection
    CreateRelayRequest:
      type: object
      required:
      - to
      properties:
        address:
          type:
          - string
          - 'null'
          description: |-
            The address of the relay;
            The resulting address in the relay will be `forward_to_{address}`;
            When omitted, the name will be used;
        authorized:
          type:
          - string
          - 'null'
          description: |-
            Only allows relay node with the provided identity;
            When omitted, all identities are allowed;
          example: Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
        name:
          type:
          - string
          - 'null'
          description: |-
            Name of Relay;
            Whe omitted, a random name will be generated
        to:
          type: string
          description: Multiaddress to the node that will be used as a relay;
          example: /project/default
    CreateTicketRequest:
      type: object
      required:
      - attributes
      properties:
        attributes:
          $ref: '#/components/schemas/Attributes'
        expires-in:
          type: integer
          format: int64
          description: |-
            Duration for which the enrollment ticket is valid;
            The value is expressed in seconds.
          default: 600
          minimum: 0
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to use when contacting the Authority node;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
        project:
          oneOf:
          - $ref: '#/components/schemas/Project'
            description: Project information to use when creating the ticket;
          default:
            existing:
              name: null
        usage-count:
          type: integer
          format: int64
          description: Number of times the ticket can be used to enroll;
          default: 1
          minimum: 0
    EnrollProjectRequest:
      type: object
      required:
      - ticket
      properties:
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to enroll;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
        ticket:
          type: string
          description: |-
            Ticket to use for enrollment;
            The encoded ticket
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    GetAuthorityMemberRequest:
      type: object
      properties:
        authority:
          oneOf:
          - $ref: '#/components/schemas/Authority'
            description: Authority to use when creating the ticket;
          default:
            project:
              name: null
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to use when contacting the Authority node;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
    HostnamePort:
      type: object
      required:
      - hostname
      - port
      properties:
        hostname:
          type: string
        port:
          type: integer
          format: int32
          minimum: 0
    InletKind:
      type: string
      enum:
      - regular
      - udp-pucture
      - only-udp-pucture
      - privileged
      - privileged-udp-puncture
      - privileged-only-udp-puncture
    InletStatus:
      type: object
      required:
      - name
      - status
      - bind-address
      - to
      - privileged
      properties:
        bind-address:
          $ref: '#/components/schemas/HostnamePort'
          description: Bind address of the TCP Inlet
        current-route:
          type:
          - string
          - 'null'
          description: The current route of the TCP Inlet, populated only when the status is `up`
        name:
          type: string
          description: Name of the TCP Inlet
        privileged:
          type: boolean
          description: Whether the TCP Inlet is of privileged kind
        status:
          $ref: '#/components/schemas/ConnectionStatus'
          description: Status of the TCP Inlet
        to:
          type: string
          description: Multiaddress to the TCP Outlet
    InletTls:
      oneOf:
      - type: string
        enum:
        - none
      - type: string
        enum:
        - project-tls
      - type: object
        required:
        - custom-tls-provider
        properties:
          custom-tls-provider:
            type: object
            required:
            - tls-certificate-provider
            properties:
              tls-certificate-provider:
                type: string
                description: |-
                  Multiaddress to a certificate provider;
                  Typical: /project/default/service/tls_certificate_provider
    ListAuthorityMembersRequest:
      type: object
      properties:
        authority:
          oneOf:
          - $ref: '#/components/schemas/Authority'
            description: Authority to use when creating the ticket;
          default:
            project:
              name: null
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to use when contacting the Authority node;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
    NodeName:
      type: string
      description: |-
        The destination node name.
        Depending on the type of node resolution used, it can be a relay name
        or a dns address.
        The special value `self` can be used to refer to the current node.
    OutletKind:
      type: string
      enum:
      - regular
      - privileged
    OutletStatus:
      type: object
      required:
      - to
      - address
      - privileged
      properties:
        address:
          type: string
          description: The address of the worker, this also acts as an identifier of the TCP Outlet within the node
        privileged:
          type: boolean
          description: Whether the outlet is of privileged kind
        to:
          $ref: '#/components/schemas/HostnamePort'
          description: The address of the outlet
    OutletTls:
      type: string
      enum:
      - none
      - validate
    Project:
      oneOf:
      - type: object
        required:
        - existing
        properties:
          existing:
            type: object
            properties:
              name:
                type:
                - string
                - 'null'
                description: |-
                  Name of the project
                  When omitted, the default project will be used
      - type: object
        required:
        - provided
        properties:
          provided:
            type: object
            required:
            - authority_route
            - authority_change_history
            - project_route
            - project_change_history
            properties:
              authority_change_history:
                type: string
                description: Full public identity of the authority node
                example: 81825837830101583285f...
              authority_route:
                type: string
                description: Multiaddress to the node that will be used as an authority;
                example: /dnsaddr/my-authority.example.com/tcp/4001/secure/api
              project_change_history:
                type: string
                description: Full public identity of the project node
                example: 81825837830101583285f...
              project_name:
                type: string
                description: |-
                  Name of the project;
                  When omitted, the default project will be used
                default: default
                example: my-project
              project_route:
                type: string
                description: Multiaddress to the node that will be used as a project;
                example: /dnsaddr/my-project.example.com/tcp/4000/service/api
    RelayStatus:
      type: object
      required:
      - name
      - to
      - status
      properties:
        name:
          type: string
          description: Name of the relay
        remote-address:
          type:
          - string
          - 'null'
          description: |-
            The address of the relay within the relay;
            Usually it follows the form `forward_to_{address}`
        status:
          $ref: '#/components/schemas/ConnectionStatus'
          description: The status of the relay
        to:
          type: string
          description: Multiaddress to the node that is used as a relay
    RemoveAuthorityMemberRequest:
      type: object
      properties:
        authority:
          oneOf:
          - $ref: '#/components/schemas/Authority'
            description: Authority to use when creating the ticket;
          default:
            project:
              name: null
        identity:
          type:
          - string
          - 'null'
          description: |-
            Identity to use when contacting the Authority node;
            When omitted, the default identity will be used
          examples:
          - Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a
    Ticket:
      type: object
      required:
      - encoded
      properties:
        encoded:
          type: string
          description: |-
            Encoded ticket;
            The ticket is encoded in a format that is understood by the Ockam Command and it may
            vary over time.
    UpdateInletRequest:
      type: object
      properties:
        allow:
          type:
          - string
          - 'null'
          description: |-
            Policy expression that will be used for access control to the TCP Inlet;
            When omitted, the policy set for the "tcp-inlet" resource type will be used.
            [Learn more about Policies expression on the Ockam documentation](https://docs.ockam.io/reference/protocols/access-controls).
    UpdateOutletRequest:
      type: object
      properties:
        allow:
          type:
          - string
          - 'null'
          description: |-
            Policy expression that will be used for access control to the TCP Outlet;
            by default, the policy set for the "tcp-outlet" resource type will be used.
            [Learn more about Policies expression on the Ockam documentation](https://docs.ockam.io/reference/protocols/access-controls).
  securitySchemes:
    token:
      type: http
      scheme: bearer
      bearerFormat: Plaintext
      description: A simple token authentication, this token can be set as startup parameter
security:
- token: []
tags:
- name: Portals
  description: |2

    A TCP Inlet and TCP Outlet together form a Portal, working hand in hand with Relays. A TCP Inlet
    defines where a node, running on another machine, listens for connections. The Inlet's route
    provides information on how to forward traffic to the Outlet (its address). Relays allow you to
    establish end-to-end protocols with services that operate in remote private networks.
  externalDocs:
    url: https://docs.ockam.io/reference/command/advanced-routing#portal
    description: Learn more about Portals on Ockam Command documentation
- name: Relays
  description: |2

    Relays make it possible to establish end-to-end protocols with services operating in a remote
    private networks, without requiring a remote service to expose listening ports to an outside hostile
    network like the Internet.
  externalDocs:
    url: https://docs.ockam.io/reference/command/advanced-routing#relays
    description: Learn more about Relays on Ockam Command documentation
- name: Tickets
  description: |2

    The ticket is plain text representing a one-time use token and the non-sensitive data about the
    Project, like the route to reach it and the Project Identity Identifier, which will be used to
    validate the Project Identity. The ticket itself can be stored in an environment variable, or a
    file.
- name: Authority Members
  description: |2

    An Ockam Authority is a Ockam node running a set of services dedicated to managing credentials
    and identities.
    The Ockam Authority keeps a list of members, which are entitled to receive credentials with proper
    attributes.
externalDocs:
  url: https://docs.ockam.io/
  description: Ockam documentation

[etorreborre]

🎼