subvt_app_service.yml

swagger: "2.0"
info:
  description: "SubVT application service endpoints."
  version: "0.1.0"
  title: "SubVT Application Service"
  termsOfService: "https://subvt-test.helikon.io"
  contact:
    email: "info@helikon.io"
  license:
    name: "GPL-3.0"
    url: "https://www.gnu.org/licenses/gpl-3.0.en.html"
host: "78.181.100.160:17778"
basePath: "/app"
tags:
  - name: "network"
    description: "Services related to the networks supported by SubVT."
  - name: "notification"
    description: "All the services related to notifications, and notification metadata."
  - name: "user"
    description: "User services."
  - name: "validator"
    description: "User-validator services."
schemes:
  - "http"
paths:
  /network:
    get:
      tags:
        - "network"
      summary: "Get network list"
      description: "Get a list of all supported networks."
      produces:
        - "application/json"
      operationId: "getNetworkList"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Network"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /notification/channel:
    get:
      tags:
        - "notification"
      summary: "Get notification channel list"
      description: "Get a list of all notification channels (email, sms, apns, fcm, etc.)."
      produces:
        - "application/json"
      operationId: "getNotificationChannelList"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/NotificationChannel"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /notification/type:
    get:
      tags:
        - "notification"
      summary: "Get notification type list"
      description: "Get a list of all notification types (block authored, new/lost/changed nomination, validator chilled, offline offence etc.)."
      produces:
        - "application/json"
      operationId: "getNotificationTypeList"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/NotificationType"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user:
    post:
      tags:
        - "user"
      summary: "Create new user"
      description: "Create a new SubVT user. Request body has only the public key of the user."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      operationId: "createUser"
      parameters:
        - name: "user"
          in: "body"
          description: "User public key."
          required: true
          schema:
            $ref: "#/definitions/CreateUserRequest"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/User"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "409":
          description: "User exists with the provided public key"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/notification/channel:
    get:
      tags: [ "notification", "user" ]
      summary: "Get user notification channels list"
      description: "Get the list of the user's notification channels."
      produces:
        - "application/json"
      operationId: "getUserNotificationChannelList"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/notification/channel`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/UserNotificationChannel"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
    post:
      tags: [ "notification", "user" ]
      summary: "Create user notification channel"
      description: "Create a new notification channel for the user."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      operationId: "createUserNotificationChannel"
      parameters:
        - name: "signature"
          in: "header"
          description: "Request body signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "notification_channel"
          in: "body"
          description: "Notification channel."
          required: true
          schema:
            $ref: "#/definitions/CreateNotificationChannelRequest"
      responses:
        "200":
          description: "Operation successful"
          schema:
            $ref: "#/definitions/UserNotificationChannel"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User or notification channel not found"
          schema:
            $ref: "#/definitions/Error"
        "409":
          description: "Given notification channel exists for the user"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/notification/channel/{channel_id}:
    delete:
      tags: [ "notification", "user" ]
      summary: "Delete user notification channel"
      description: "Delete the notification channel from the user's notification channels."
      produces:
        - "application/json"
      operationId: "deleteUserNotificationChannel"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/notification/channel/2`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "channel_id"
          in: "path"
          description: "User notification channel id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "204":
          description: "Operation successful"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User notification channel not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/notification/rule:
    get:
      tags: [ "notification", "user" ]
      summary: "Get user notification rule list"
      description: "Get the list of the user's notification rules."
      produces:
        - "application/json"
      operationId: "getUserNotificationRuleList"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/notification/rule`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/UserNotificationRule"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
    post:
      tags: [ "notification", "user" ]
      summary: "Create a user notification rule"
      description: "Create a new notification rule for the user."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      operationId: "createUserNotificationRule"
      parameters:
        - name: "signature"
          in: "header"
          description: "Request body signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "notification_rule"
          in: "body"
          description: "Notificaiton rule."
          required: true
          schema:
            $ref: "#/definitions/CreateUserNotificationRuleRequest"
      responses:
        "200":
          description: "Operation successful"
          schema:
            $ref: "#/definitions/UserNotificationRule"
        "400":
          description: "Bad request - could be a validation error"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User, notification type, network, validator or user notification channel not found."
          schema:
            $ref: "#/definitions/Error"
        "409":
          description: "User validator exists with the same network and account ids"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/notification/rule/{user_notification_rule_id}:
    delete:
      tags: [ "notification", "user" ]
      summary: "Delete user notification rule"
      description: "Delete the notification rule from the user's rule list."
      produces:
        - "application/json"
      operationId: "deleteUserNoticationRule"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/notification/rule/214`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "user_notification_rule_id"
          in: "path"
          description: "User notification rule id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "204":
          description: "Operation successful"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User notification rule not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/validator:
    get:
      tags: [ "validator", "user" ]
      summary: "Get user validator list"
      description: "Get the list of the user's validators."
      produces:
        - "application/json"
      operationId: "getUserValidatorList"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/validator`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "200":
          description: "Operation successful"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/UserValidator"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
    post:
      tags: [ "validator", "user" ]
      summary: "Create user validator"
      description: "Create a new validator for the user."
      consumes:
        - "application/json"
      produces:
        - "application/json"
      operationId: "createUserValidator"
      parameters:
        - name: "signature"
          in: "header"
          description: "Request body signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "validator"
          in: "body"
          description: "Validator."
          required: true
          schema:
            $ref: "#/definitions/CreateUserValidatorRequest"
      responses:
        "200":
          description: "Operation successful"
          schema:
            $ref: "#/definitions/UserValidator"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User or network not found"
          schema:
            $ref: "#/definitions/Error"
        "409":
          description: "User validator exists with the same network and account ids"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
  /user/{user_id}/validator/{user_validator_id}:
    delete:
      tags: [ "validator", "user" ]
      summary: "Delete user validator"
      description: "Delete the validator from the user's validator list."
      produces:
        - "application/json"
      operationId: "deleteUserValidator"
      parameters:
        - name: "signature"
          in: "header"
          description: "Relative request path (e.g. `/user/7465/validator/214`) signed with the user's private key."
          required: true
          type: "string"
        - name: "user_id"
          in: "path"
          description: "User id."
          required: true
          type: "integer"
          format: "int64"
        - name: "user_validator_id"
          in: "path"
          description: "User validator id."
          required: true
          type: "integer"
          format: "int64"
      responses:
        "204":
          description: "Operation successful"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/Error"
        "403":
          description: "Forbidden: invalid signature"
          schema:
            $ref: "#/definitions/Error"
        "404":
          description: "User notification channel not found"
          schema:
            $ref: "#/definitions/Error"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/Error"
definitions:
  CreateNotificationChannelRequest:
    type: "object"
    required: [ "channel_code", "target" ]
    properties:
      channel_code:
        type: "string"
        description: "Short code of the notification channel (email, fcm, apns, etc.)."
      target:
        type: "string"
        description: "Notification target (e.g. phone number for SMS, email address for email, etc.)."
  CreateUserNotificationRuleRequest:
    type: "object"
    required: [ "notification_type_code" ]
    properties:
      notification_type_code:
        type: "string"
        description: "Notification type."
      name:
        type: "string"
        description: "Optional arbitrary name given to the rule by the user."
      network_id:
        type: "integer"
        format: "int64"
        description: "Id of the network that the notification is to be defined for. Null if for all networks."
      is_for_all_validators:
        type: "boolean"
        description: "True if the rule is defined for all validators of the selected network, or for all validators if network is null."
      user_validator_ids:
        type: "array"
        description: "Database ids of the user-validators that the notification rule is to be defined for. Empty if for all validators."
        items:
          type: "integer"
          format: "int64"
      period_type:
        type: "string"
        enum: [ "off", "immediate", "hour", "day", "era", "epoch" ]
        description: "Period type for the notification rule."
      period:
        type: "integer"
        format: "int32"
        description: "Together with `period_type` it defines the notification period. E.g. every 2 epoch."
      user_notification_channel_ids:
        type: "array"
        description: "Database ids of the user's notification channels that the notifications resulting from this rule would be targeted at."
        items:
          type: "integer"
          format: "int64"
      parameters:
        type: "array"
        description: "Parameters for the rule. Non-optional parameters have to be supplied."
        items:
          type: "object"
          properties:
            parameter_type_id:
              type: "integer"
              format: "int64"
              description: "Database id of the parameter type."
            value:
              type: "string"
              description: "Parameter value."
  CreateUserRequest:
    type: "object"
    required: [ "public_key_hex" ]
    properties:
      public_key_hex:
        type: "string"
        description: "Hex-encoded 32-byte public key of the user public key, 0x-prefixed or not."
  CreateUserValidatorRequest:
    type: "object"
    required: [ "network_id", "validator_account_id" ]
    properties:
      network_id:
        type: "integer"
        format: "int64"
        description: "Id of the network that the validator is on."
      validator_account_id:
        type: "string"
        description: "Hex-encoded 32-byte account id of the validator, 0x-prefixed."
  Error:
    type: "object"
    required: [ "description" ]
    properties:
      description:
        type: "string"
        description: "Error description."
  Network:
    type: "object"
    required: [ "id", "hash", "name", "ss58_prefix" ]
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "SubVT network id."
      hash:
        type: "string"
        description: "Hex-encoded 32-byte genesis block hash of the network (0x-prefixed)."
      name:
        type: "string"
        description: "Network name (e.g. Polkadot, Kusama)."
      ss58_prefix:
        type: "integer"
        format: "int64"
        description: "Network's SS58 prefix as defined in the SS58 [registry](https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json)."
      network_status_service_url:
        type: "string"
        description: "URL for the SubVT network status WS RPC service for the network."
      report_service_url:
        type: "string"
        description: "URL for the SubVT report REST service for the network."
      validator_details_service_url:
        type: "string"
        description: "URL for the SubVT validator details WS RPC service for the network."
      active_validator_list_service_url:
        type: "string"
        description: "URL for the SubVT active validator list WS RPC service for the network."
      inactive_validator_list_service_url:
        type: "string"
        description: "URL for the SubVT inactive validator list WS RPC service for the network."
  NotificationChannel:
    type: "object"
    required: [ "code" ]
    properties:
      code:
        type: "string"
        description: "Short code of the notification channel (email, fcm, apns, etc.)."
  NotificationType:
    type: "object"
    required: [ "code", "param_types" ]
    properties:
      code:
        type: "string"
        description: "Code name of the notification type."
      param_types:
        type: "array"
        items:
          $ref: "#/definitions/NotificationParamType"
        description: "Notification parameter definition list."
  NotificationParamType:
    type: "object"
    required: [ "id", "notification_type_code", "order", "code", "type", "is_optional" ]
    properties:
      id:
        type: "integer"
        format: "int64"
      notification_type_code:
        type: "string"
        description: "Code name of the notification type that the parameter belongs to."
      order:
        type: "integer"
        format: "int32"
        description: "Order of the parameter. Used when displaying the parameters in the correct order."
      code:
        type: "string"
        description: "Code name for the parameter."
      type:
        type: "string"
        enum: [ "string", "integer", "balance", "float", "boolean" ]
        description: "Data type of the parameter. Balance type is the string representation of a 64-bit unsigned integer."
      min:
        type: "string"
        description: "(Optional) Minimum value of the parameter. Used for validation."
      max:
        type: "string"
        description: "(Optional) Minimum value of the parameter. Used for validation."
      is_optional:
        type: "boolean"
        description: "Whether the parameter is optional."
  User:
    type: "object"
    required: [ "id", "public_key_hex" ]
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "User id."
      public_key_hex:
        type: "string"
        description: "Hex-encoded 32-byte public key of the user public key, 0x-prefixed or not."
  UserNotificationChannel:
    type: "object"
    required: [ "id", "user_id", "channel_code", "target" ]
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "User notification channel id."
      user_id:
        type: "integer"
        format: "int64"
        description: "User id."
      channel_code:
        type: "string"
        description: "Short code of the notification channel (email, fcm, apns, etc.)."
      target:
        type: "string"
        description: "Notification target (e.g. phone number for SMS, email address for email, etc.)."
  UserNotificationRule:
    type: "object"
    required: [ "id", "user_id", "notification_type", "is_for_all_validators", "period_type", "period", "validators", "notification_channels", "parameters" ]
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "User notification rule id."
      user_id:
        type: "integer"
        format: "int64"
        description: "User id."
      notification_type:
        $ref: "#/definitions/NotificationType"
      name:
        type: "string"
        description: "Optional arbitrary name given to the rule by the user."
      network:
        $ref: "#/definitions/Network"
      is_for_all_validators:
        type: "boolean"
        description: "True if the rule is defined for all validators of the selected network, or for all validators if network is null."
      period_type:
        type: "string"
        enum: [ "off", "immediate", "hour", "day", "era", "epoch" ]
        description: "Period type for the notification rule."
      period:
        type: "integer"
        format: "int32"
        description: "Together with `period_type` it defines the notification period. E.g. every 2 epoch."
      validators:
        type: "array"
        description: "List of the validators that the notification rule is defined for. Empty for a rule for all validators."
        items:
          $ref: "#/definitions/UserValidator"
      notification_channels:
        type: "array"
        description: "Notification target channels."
        items:
          $ref: "#/definitions/UserNotificationChannel"
      parameters:
        type: "array"
        description: "Notification rule parameters."
        items:
          $ref: "#/definitions/UserNotificationRuleParameter"
      notes:
        type: "string"
        description: "Optional arbitrary notes for the rule by the user."
  UserNotificationRuleParameter:
    type: "object"
    required: [ "" ]
    properties:
      user_notification_rule_id:
        type: "integer"
        format: "int64"
        description: "Database id of the notification rule that this parameter belongs to."
      parameter_type_id:
        type: "integer"
        format: "int64"
        description: "Database id of the parameter type."
      parameter_type_code:
        type: "string"
        description: "The descriptive code for the parameter, copied from the parameter type."
      order:
        type: "integer"
        format: "int32"
        description: "Order of the parameter. copied from the parameter type."
      value:
        type: "string"
        description: "Parameter value."
  UserValidator:
    type: "object"
    required: [ "id", "user_id", "network_id", "validator_account_id" ]
    properties:
      id:
        type: "integer"
        format: "int64"
        description: "User notification channel id."
      user_id:
        type: "integer"
        format: "int64"
        description: "User id."
      network_id:
        type: "integer"
        format: "int64"
        description: "Id of the network that the validator is on."
      validator_account_id:
        type: "string"
        description: "Hex-encoded 32-byte account id of the validator, 0x-prefixed."