openapi-spec.yaml

openapi: "3.0.3"
info:
  title: WireGuard RESTful API
  description: |
    Manage WireGuard VPN tunnels by RESTful manner.

    Supported features:

      * Manage device: create, update, and delete wireguard interface
      * Manage device's ip addresses: attache or detach ip addresses to the netowrk interface
      * Manage device's peers: create, update, and delete peers
      * Peer's QR code, for use in WireGuard & ForestVPN client

    ForestVPN client may be used as alternative client with enabled P2P technology over WireGuard tunnelling.
    Read more on https://forestvpn.com/
  termsOfService: https://forestvpn.com/terms/
  contact:
    name: ForestVPN
    url: https://forestvpn.com/
    email: support@forestvpn.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: "1.0"

externalDocs:
  description: Documentation of wgrest
  url: https://forestvpn.com/docs/wgrest/

servers:
  - url: '{scheme}://{host}/v1'
    variables:
      host:
        default: "example.com"
      scheme:
        enum:
          - 'https'
          - 'http'
        default: 'https'

security:
  - bearerAuth: [ ]

paths:
  /devices/:
    get:
      summary: Devices list
      operationId: ListDevices
      tags:
        - device
      parameters:
        - in: query
          name: per_page
          description: Number of WireGuard devices per page. Default is 100
          schema:
            type: number
        - in: query
          name: page
          description: Page number. Default is 0
          schema:
            type: number
      responses:
        '200':
          description: ok
          headers:
            Link:
              schema:
                type: string
                description: https://docs.github.com/en/rest/guides/traversing-with-pagination
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Device"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create new device
      operationId: CreateDevice
      tags:
        - device
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceCreateOrUpdateRequest"
      responses:
        201:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        409:
          description: Device exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/:
    get:
      summary: Get device info
      operationId: GetDevice
      tags:
        - device
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        404:
          description: not found
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete Device
      operationId: DeleteDevice
      tags:
        - device
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        204:
          description: No content
        404:
          description: Not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: Update device
      operationId: UpdateDevice
      tags:
        - device
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceCreateOrUpdateRequest"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        404:
          description: Not found
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/options/:
    get:
      summary: Get device options
      operationId: GetDeviceOptions
      tags:
        - device
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceOptions"
        404:
          description: not found
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: Update device's options
      operationId: UpdateDeviceOptions
      tags:
        - device
      parameters:
        - in: path
          name: name
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceOptionsUpdateRequest"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceOptions"
        404:
          description: Not found
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/peers/:
    get:
      summary: Peers list
      operationId: ListDevicePeers
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: query
          name: per_page
          description: Number of WireGuard device's peers per page. Default is 100
          schema:
            type: number
        - in: query
          name: page
          description: Page number. Default is 0
          schema:
            type: number
        - in: query
          name: q
          description: Search query
          schema:
            type: string
        - in: query
          name: sort
          description: Sort field
          schema:
            type: string
            enum:
              - pub_key
              - receive_bytes
              - -receive_bytes
              - transmit_bytes
              - -transmit_bytes
              - total_bytes
              - -total_bytes
              - last_handshake_time
              - -last_handshake_time
      responses:
        200:
          description: Ok
          headers:
            Link:
              schema:
                type: string
                description: https://docs.github.com/en/rest/guides/traversing-with-pagination
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Peer"
        404:
          description: Device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create new device peer
      operationId: CreateDevicePeer
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeerCreateOrUpdateRequest"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Peer"
        404:
          description: Device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/peers/{urlSafePubKey}/:
    get:
      summary: Get device peer info
      operationId: GetDevicePeer
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: path
          name: urlSafePubKey
          description: Peer's url safe public key
          required: true
          schema:
            type: string
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Peer"
        404:
          description: Peer or device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: Update device's peer
      operationId: UpdateDevicePeer
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: path
          name: urlSafePubKey
          description: Peer's url safe public key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeerCreateOrUpdateRequest"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Peer"
        404:
          description: Peer or device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete device's peer
      operationId: DeleteDevicePeer
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: path
          name: urlSafePubKey
          description: Peer's url safe public key
          required: true
          schema:
            type: string
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Peer"
        404:
          description: Peer or device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/peers/{urlSafePubKey}/quick.conf:
    get:
      summary: Get device peer quick config
      operationId: GetDevicePeerQuickConfig
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: path
          name: urlSafePubKey
          description: Peer's url safe public key
          required: true
          schema:
            type: string
      responses:
        200:
          description: Ok
          content:
            text/plain:
              schema:
                type: string
                format: binary
        404:
          description: Peer or device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /devices/{name}/peers/{urlSafePubKey}/quick.conf.png:
    get:
      summary: Get device peer quick config QR code
      operationId: GetDevicePeerQuickConfigQRCodePNG
      tags:
        - device
      parameters:
        - in: path
          name: name
          description: Device's name
          required: true
          schema:
            type: string
        - in: path
          name: urlSafePubKey
          description: Peer's url safe public key
          required: true
          schema:
            type: string
        - in: query
          name: width
          description: QR code's width & height. Default is 256px.
          schema:
            type: string
      responses:
        200:
          description: Ok
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        404:
          description: Peer or device not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization token
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          example: device_does_not_exist
        message:
          type: string
          description: Error's short description
          example: Device "wg0" does'n exist
        detail:
          type: string
          description: Error's detail description
    DeviceOptionsUpdateRequest:
      type: object
      description: Device options
      properties:
        allowed_ips:
          type: array
          items:
            type: string
          description: Device's allowed ips, it might be any of IPv4 or IPv6 addresses in CIDR notation.
            It might be owervrite in peer and device config.
          example:
            - 0.0.0.0/0
            - ::0/0
          nullable: true
        dns_servers:
          type: array
          items:
            type: string
          description: Interface's DNS servers.
          example:
            - 8.8.8.8
            - 2001:4860:4860::8888
          nullable: true
        host:
          type: string
          description: Device host, it might be domain name or IPv4/IPv6 address.
            It is used for external/internal connection
          example: "1.2.3.4"
          nullable: true
    DeviceOptions:
      type: object
      description: Device options
      required:
        - allowed_ips
        - dns_servers
        - host
      properties:
        allowed_ips:
          type: array
          items:
            type: string
          description: Device's allowed ips, it might be any of IPv4 or IPv6 addresses in CIDR notation.
            It might be owervrite in peer and device config.
          example:
            - 0.0.0.0/0
            - ::0/0
        dns_servers:
          type: array
          items:
            type: string
          description: Interface's DNS servers.
          example:
            - 8.8.8.8
            - 2001:4860:4860::8888
        host:
          type: string
          description: Device host, it might be domain name or IPv4/IPv6 address.
            It is used for external/internal connection
          example: "1.2.3.4"
    DeviceCreateOrUpdateRequest:
      type: object
      description: Device params that might be used due to creation or updation process
      properties:
        name:
          type: string
          description: WireGuard device name. Usually it is network interface name
          example: wg0
          nullable: true
        listen_port:
          type: integer
          format: int32
          description: WireGuard device listen port.
          example: 51820
          nullable: true
        private_key:
          type: string
          description: WireGuard device private key encoded by base64.
          example: wBHGU3RiK/IFWXAF2jbHjGSDAKEO2ddcsZFEWcQ+qGc=
          nullable: true
        firewall_mark:
          type: integer
          format: int32
          description: WireGuard device firewall mark.
          example: 10
          nullable: true
        networks:
          type: array
          items:
            type: string
          description: IPv4 or IPv6 addresses in CIDR notation
          example:
            - 10.71.25.1/24
            - fd42:21:21::1/64
          nullable: true
    Device:
      type: object
      description: Information about wireguard device.
      required:
        - name
        - listen_port
        - public_key
        - private_key
        - firewall_mark
        - networks
        - peers_count
        - total_receive_bytes
        - total_transmit_bytes
      properties:
        name:
          type: string
          description: WireGuard device name. Usually it is network interface name
          example: wg0
        listen_port:
          type: integer
          format: int32
          description: WireGuard device listen port.
          example: 51820
        public_key:
          type: string
          description: WireGuard device public key encoded by base64.
          example: QFjZjxa2sgwnmGT4NqyRoeNk31AlHjVxHNEH/qY/2no=
        firewall_mark:
          type: integer
          format: int32
          description: WireGuard device firewall mark.
          example: 10
        networks:
          type: array
          items:
            type: string
          description: IPv4 or IPv6 addresses in CIDR notation
          example:
            - 10.71.25.1/24
            - fd42:21:21::1/64
        peers_count:
          type: integer
          format: int32
          description: WireGuard device's peers count
          example: 10
        total_receive_bytes:
          type: integer
          format: int64
          description: WireGuard device's peers total receive bytes
          example: 59984733
        total_transmit_bytes:
          type: integer
          format: int64
          description: WireGuard device's peers total transmit bytes
          example: 45331987
    PeerCreateOrUpdateRequest:
      type: object
      description: Peer params that might be used due to creation or updation process
      properties:
        private_key:
          type: string
          description: Base64 encoded private key. If present it will be stored in persistent storage.
          example: gD89VQVXPAEpXuIyHOujw1wF4njIBtaSLvqAatBAuWY=
          nullable: true
        public_key:
          type: string
          description: Base64 encoded public key
          example: qnPJFozrAnrTjap5VjO30bUeLvhkZEEZx48w2RqMpRA=
          nullable: true
        preshared_key:
          type: string
          description: Base64 encoded preshared key
          example: c2m+JtxpcRP6pztdDFRHnOx75SI+QyBDba1+BEbQaiA=
          nullable: true
        allowed_ips:
          type: array
          items:
            type: string
          description: Peer's allowed ips, it might be any of IPv4 or IPv6 addresses in CIDR notation
          example:
            - 10.71.25.51/32
            - fd42:21:21::51/128
          nullable: true
        persistent_keepalive_interval:
          type: string
          description: Peer's persistend keepalive interval. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
          example: "25s"
        endpoint:
          type: string
          description: Peer's endpoint in host:port format
          example: "1.2.3.4:2345"
    Peer:
      type: object
      description: Information about wireguard peer.
      required:
        - public_key
        - url_safe_public_key
        - allowed_ips
        - persistent_keepalive_interval
        - last_handshake_time
        - endpoint
        - receive_bytes
        - transmit_bytes
      properties:
        public_key:
          type: string
          description: Base64 encoded public key
          example: 0DGpyohLU+T1qAemWVWsNd1nwy3ZBAG7U4JJ/ZA+fWA=
        url_safe_public_key:
          type: string
          description: URL safe base64 encoded public key. It is usefull to use in peers api endpoint.
          example: 0DGpyohLU-T1qAemWVWsNd1nwy3ZBAG7U4JJ_ZA-fWA
        preshared_key:
          type: string
          description: Base64 encoded preshared key
          example: c2m+JtxpcRP6pztdDFRHnOx75SI+QyBDba1+BEbQaiA=
        allowed_ips:
          type: array
          items:
            type: string
          description: Peer's allowed ips, it might be any of IPv4 or IPv6 addresses in CIDR notation
          example:
            - 10.71.25.51/32
            - fd42:21:21::51/128
        last_handshake_time:
          type: string
          format: date-time
          description: Peer's last handshake time formated in RFC3339
          example: ""
        persistent_keepalive_interval:
          type: string
          description: Peer's persistend keepalive interval in
          example: "25s"
        endpoint:
          type: string
          description: Peer's endpoint in host:port format
          example: "1.2.3.4:2345"
        receive_bytes:
          type: integer
          format: int64
          description: Peer's receive bytes
          example: 587732
        transmit_bytes:
          type: integer
          format: int64
          description: Peer's transmit bytes
          example: 432445