Incus network-peers API

swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates network-peers API
  version: '1.0'
tags:
- name: network-peers
paths:
  /1.0/networks/{networkName}/peers:
    get:
      description: Returns a list of network peers (URLs).
      operationId: network_peers_get
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/networks/mybr0/peers/my-peer-1\",\n  \"/1.0/networks/mybr0/peers/my-peer-2\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network peers
      tags:
      - network-peers
    post:
      consumes:
      - application/json
      description: Initiates/creates a new network peering.
      operationId: network_peers_post
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Peer
        in: body
        name: peer
        required: true
        schema:
          $ref: '#/definitions/NetworkPeersPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '202':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a network peer
      tags:
      - network-peers
  /1.0/networks/{networkName}/peers/{peerName}:
    delete:
      description: Removes the network peering.
      operationId: network_peer_delete
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Peer name
        in: path
        name: peerName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the network peer
      tags:
      - network-peers
    get:
      description: Gets a specific network peering.
      operationId: network_peer_get
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Peer name
        in: path
        name: peerName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Peer
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/NetworkPeer'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network peer
      tags:
      - network-peers
    patch:
      consumes:
      - application/json
      description: Updates a subset of the network peering configuration.
      operationId: network_peer_patch
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Peer name
        in: path
        name: peerName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Peer configuration
        in: body
        name: Peer
        required: true
        schema:
          $ref: '#/definitions/NetworkPeerPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the network peer
      tags:
      - network-peers
    put:
      consumes:
      - application/json
      description: Updates the entire network peering configuration.
      operationId: network_peer_put
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Peer name
        in: path
        name: peerName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Peer configuration
        in: body
        name: peer
        required: true
        schema:
          $ref: '#/definitions/NetworkPeerPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the network peer
      tags:
      - network-peers
  /1.0/networks/{networkName}/peers?recursion=1:
    get:
      description: Returns a list of network peers (structs).
      operationId: network_peer_get_recursion1
      parameters:
      - description: Network name
        in: path
        name: networkName
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of network peers
                items:
                  $ref: '#/definitions/NetworkPeer'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network peers
      tags:
      - network-peers
definitions:
  NetworkPeer:
    properties:
      config:
        description: Peer configuration map (refer to doc/network-peers.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the peer
        example: Peering with network1 in project1
        type: string
        x-go-name: Description
      name:
        description: Name of the peer
        example: project1-network1
        readOnly: true
        type: string
        x-go-name: Name
      status:
        description: The state of the peering
        example: Pending
        readOnly: true
        type: string
        x-go-name: Status
      target_integration:
        description: Name of the target integration
        example: ovn-ic1
        type: string
        x-go-name: TargetIntegration
      target_network:
        description: Name of the target network
        example: network1
        readOnly: true
        type: string
        x-go-name: TargetNetwork
      target_project:
        description: Name of the target project
        example: project1
        readOnly: true
        type: string
        x-go-name: TargetProject
      type:
        description: Type of peer
        example: local
        type: string
        x-go-name: Type
      used_by:
        description: List of URLs of objects using this network peering
        example:
        - /1.0/network-acls/test
        - /1.0/network-acls/foo
        items:
          type: string
        readOnly: true
        type: array
        x-go-name: UsedBy
    title: NetworkPeer used for displaying a network peering.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkPeerPut:
    description: NetworkPeerPut represents the modifiable fields of a network peering
    properties:
      config:
        description: Peer configuration map (refer to doc/network-peers.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the peer
        example: Peering with network1 in project1
        type: string
        x-go-name: Description
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkPeersPost:
    description: NetworkPeersPost represents the fields of a new network peering
    properties:
      config:
        description: Peer configuration map (refer to doc/network-peers.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the peer
        example: Peering with network1 in project1
        type: string
        x-go-name: Description
      name:
        description: Name of the peer
        example: project1-network1
        type: string
        x-go-name: Name
      target_integration:
        description: Name of the target integration
        example: ovn-ic1
        type: string
        x-go-name: TargetIntegration
      target_network:
        description: Name of the target network
        example: network1
        type: string
        x-go-name: TargetNetwork
      target_project:
        description: Name of the target project
        example: project1
        type: string
        x-go-name: TargetProject
      type:
        description: Type of peer
        example: local
        type: string
        x-go-name: Type
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
responses:
  Forbidden:
    description: Forbidden
    schema:
      properties:
        error:
          example: not authorized
          type: string
          x-go-name: Error
        error_code:
          example: 403
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  BadRequest:
    description: Bad Request
    schema:
      properties:
        error:
          example: bad request
          type: string
          x-go-name: Error
        error_code:
          example: 400
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  PreconditionFailed:
    description: Precondition Failed
    schema:
      properties:
        error:
          example: precondition failed
          type: string
          x-go-name: Error
        error_code:
          example: 412
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  EmptySyncResponse:
    description: Empty sync response
    schema:
      properties:
        status:
          example: Success
          type: string
          x-go-name: Status
        status_code:
          example: 200
          format: int64
          type: integer
          x-go-name: StatusCode
        type:
          example: sync
          type: string
          x-go-name: Type
      type: object
  InternalServerError:
    description: Internal Server Error
    schema:
      properties:
        error:
          example: internal server error
          type: string
          x-go-name: Error
        error_code:
          example: 500
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object