openapi: "3.0.2"
info:
  title: Interledger-rs API Specification
  version: "1.0"
servers:
  - url: https://rs3.xpring.dev
tags:
  - name: admins
    description: Secured Admin-only calls
  - name: users
    description: Operations available only to authenticated users
paths:
  # Health Check
  /:
    get:
      summary: Node health check
      responses:
        "200":
          description: The node's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeInformation"

  # Default SPSP Account
  /.well_known/pay:
    get:
      summary: The default SPSP account used on the node. This endpoint is only enabled if the node is run with the configuration option ILP_DEFAULT_SPSP_ACCOUNT. The SPSP spec can be found at https://interledger.org/rfcs/0009-simple-payment-setup-protocol/
      responses:
        "200":
          description: The node's SPSP information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpSpInformation"
  # Adjust tracing level
  /tracing-level:
    put:
      summary: Adjusts the node's tracing level
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      requestBody:
        required: true
        description: The desired log level (RUST_LOG format)
        content:
          text/plain:
            schema:
              type: string
              example: "interledger=trace"
      responses:
        "200":
          description: The new log level applied on the node
          content:
            text/plain:
              example: "Logging level changed to: interledger=trace"
  # Accounts endpoints
  /accounts:
    get:
      summary: Returns all accounts on the node
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      responses:
        "200":
          description: Accounts on the node
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Account"
    post:
      summary: Adds a new user on the node
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      requestBody:
        description: The details of the account to be added
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountDetails"
      responses:
        "200":
          description: The inserted account (an ID is auto-generated by the node)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"

  /accounts/{username}:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    get:
      summary: Gets an account's information
      tags:
        - admins
        - users
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the account's or administrator's authorization
      responses:
        "200":
          description: The requested account's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
    put:
      summary: Edit an account's information. This is an administrator-only call which allows modification of any field of the account, not to be confused with the /accounts/:username/settings endpoint which allows a user to edit some of their authorization related data.
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with administrator's authorization
      tags:
        - admins
      requestBody:
        description: The new details for the specified account
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountDetails"
      responses:
        "200":
          description: The updated account's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
    delete:
      summary: Delete an account
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with administrator's authorization
      responses:
        "200":
          description: The deleted account's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
  /accounts/{username}/settings:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    put:
      summary: Edit an account's settings (e.g. tokens, URLs, settlement thresholds). This should not be confused with the administrator-only PUT /accounts/:username endpoint which allows changing any user parameter.
      tags:
        - admins
        - users
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the account's or administrator's authorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountDetails"
        description: The new account details for the specified username
      responses:
        "200":
          description: The updated account's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountSettings"

  /accounts/{username}/balance:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    get:
      summary: Get an account's balance
      tags:
        - admins
        - users
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the account's or administrator's authorization
      responses:
        "200":
          description: The account's balance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Balance"

  /accounts/{username}/spsp:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    get:
      summary: Get an account's SPSP information
      responses:
        "200":
          description: The account's Spsp information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpSpInformation"

  /accounts/{username}/payments:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    post:
      summary: Send payment to an account. Note that even though this is a user-only endpoint, node operators have access to server secrets, meaning that they could issue payments from any account if they wished to.
      tags:
        - users
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the account's authorization
      requestBody:
        description: The receiver's address and amount to be sent
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "200":
          description: The receipt of delivery to the receiver
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"

  /accounts/{username}/ilp:
    parameters:
      - in: path
        name: username
        schema:
          type: string
        required: true
        description: Username of the account whose information you are operating on
    post:
      summary: This endpoint is used by nodes to send ILP packets over HTTP requests as defined in ILP-over-HTTP (ILP RFC-35)
      tags:
        - users
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the account's authorization
      requestBody:
        description: The serialized packet to be sent to the peer
        content:
          text/plain:
            example: ""
      responses:
        "200":
          description: The serialized fulfill/reject packet received by the peer
          content:
            application/octet-stream:
              example: ""
  # Routing endpoints
  /routes:
    get:
      summary: Gets the routes on the node
      responses:
        "200":
          description: The node's prefix-usernames pairs for the routes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Routes"

  /routes/static:
    put:
      summary: Configures static routes for the node. These will override routes received by CCP broadcast from other nodes.
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      requestBody:
        description: New static routes. The key is a route prefix, and the value is a username of an account.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Routes"
      responses:
        "200":
          description: Returns the created static routes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Routes"

  /routes/static/{prefix}:
    put:
      summary: Configures a single static route for the node. This will override routes received by CCP broadcast from other nodes.
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
        - in: path
          name: prefix
          schema:
            type: string
          required: true
          description: The prefix which you are overriding
      requestBody:
        content:
          text/plain:
            schema:
              type: string
              example: "alice"
      responses:
        "200":
          description: The created static route
          content:
            text/plain:
              schema:
                type: string
                example: "alice"

  # Rates endpoints
  /rates:
    get:
      summary: Get all of the node's exchange rates.
      responses:
        "200":
          description: The stored exchange rates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pairs"
    put:
      summary: Sets new currency rates. Will override any previous values.
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      requestBody:
        description: The new currency rates
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pairs"
      responses:
        "200":
          description: Updated rates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pairs"

  # Engines endpoints
  /settlement/engines:
    put:
      summary: Configure the default settlement engines to use for the given asset codes. If an account is not configured with a `settlement_engine_url` but the account's `asset_code` has a settlement engine configured here, the account will automatically be set up to use that settlement engine
      tags:
        - admins
      parameters:
        - in: header
          name: authorization
          schema:
            type: string
          required: true
          description: Bearer token with the administrator's authorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SettlementEngines"
        description: Asset Code to engine URL map
      responses:
        "200":
          description: Returns the created engines
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Routes"

# Various data types returned / sent to the API
components:
  schemas:
    PaymentRequest:
      type: object
      required:
        - receiver
        - source_amount
      properties:
        receiver:
          type: string
          example: "$payment-pointer.example.com"
        source_amount:
          type: integer
          example: 100000
        slippage:
          oneOf:
            - type: number
            - type: string
          default: 0.015
          description: Maximum acceptable slippage percentage below calculated minimum exchange rate
    PaymentResponse:
      type: object
      properties:
        source_asset_scale:
          type: integer
          example: 9
        source_asset_code:
          type: string
          example: "XYZ"
        sent_amount:
          type: integer
          example: 1000000
          description: Amount fulfilled or currently in-flight, in source units
        source_amount:
          type: integer
          description: Total amount *intended* to be sent, in source units
        in_flight_amount:
          type: integer
          description: Amount in-flight (yet to be fulfilled or rejected), in source units
        delivered_amount:
          type: number
          example: 1000000
          description: Amount fulfilled and received by the recipient, in destination units
        destination_asset_scale:
          type: integer
          example: 9
        destination_asset_code:
          type: string
          example: "ABC"
        from:
          type: string
          example: "example.node_a.alice"
        to:
          type: string
          example: "example.node_b.bob.-p3zU4tXsDRCBLg8vt_U6iiyQ5pgZk4MfoCaG1wZDW8"

    NodeInformation:
      type: object
      required:
        - status
        - ilp_address
        - version
      properties:
        status:
          type: string
          example: "Ready"
        ilp_address:
          type: string
          example: "example.op1"
        version:
          type: string
          example: "0.6.0"
    SpSpInformation:
      type: object
      required:
        - destination_account
        - shared_secret
      properties:
        destination_account:
          type: string
          example: "example.op1.alice.6BNqDCEa4o9JIDOaN2X2C49o"
        shared_secret:
          type: string
          example: "rmnZu6mLrcNhki3fl3CRuzIdosQ7K6HNb9NiE49rqIY="
    Balance:
      type: object
      required:
        - balance
        - asset_code
      properties:
        balance:
          type: number
          example: 0.23
        asset_code:
          type: string
          example: "ABC"
    AccountDetails:
      type: object
      required:
        - username
        - asset_code
        - asset_scale
      properties:
        username:
          type: string
          example: Alice
        asset_scale:
          type: integer
          example: 9
        asset_code:
          type: string
          example: "ABC"
        max_packet_amount:
          type: integer
          example: 10000000000
        min_balance:
          type: integer
          example: 0
        ilp_over_http_url:
          type: string
          example: "https://example.com/accounts/our_username_on_peer/ilp"
        ilp_over_http_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_http_outgoing_token:
          type: string
          example: "our_password_on_peer"
        ilp_over_btp_url:
          type: string
          example: "btps://example.com/accounts/our_username_on_peer/ilp/btp"
        ilp_over_btp_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_btp_outgoing_token:
          type: string
          example: "our_password_on_peer"
        settlement_engine_url:
          type: string
          example: "http://engine.example.com"
        settle_threshold:
          type: integer
          example: 1000000000
        settle_to:
          type: integer
          example: 1000000000
        routing_relation:
          type: string
          example: "Peer"
        round_trip_time:
          type: integer
          example: 500
        amount_per_minute_limit:
          type: integer
          example: 1000000000
        packets_per_minute_limit:
          type: integer
          example: 10
    Account:
      type: object
      required:
        - id
        - username
        - asset_scale
        - asset_code
        - max_packet_amount
        - min_balance
        - ilp_over_http_url
        - ilp_over_http_incoming_token
        - ilp_over_http_outgoing_token
        - ilp_over_btp_url
        - ilp_over_btp_incoming_token
        - ilp_over_btp_outgoing_token
        - settlement_engine_url
        - settle_threshold
        - settle_to
        - routing_relation
        - round_trip_time
        - amount_per_minute_limit
        - packets_per_minute_limit
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        username:
          type: string
          example: Alice
        asset_scale:
          type: integer
          example: 9
        asset_code:
          type: string
          example: "ABC"
        max_packet_amount:
          type: integer
          example: 10000000000
        min_balance:
          type: integer
          example: 0
        ilp_over_http_url:
          type: string
          example: "https://example.com/accounts/our_username_on_peer/ilp"
        ilp_over_http_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_http_outgoing_token:
          type: string
          example: "our_password_on_peer"
        ilp_over_btp_url:
          type: string
          example: "btps://example.com/accounts/our_username_on_peer/ilp/btp"
        ilp_over_btp_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_btp_outgoing_token:
          type: string
          example: "our_password_on_peer"
        settlement_engine_url:
          type: string
          example: "http://engine.example.com"
        settle_threshold:
          type: integer
          example: 1000000000
        settle_to:
          type: integer
          example: 1000000000
        routing_relation:
          type: string
          example: "Peer"
        round_trip_time:
          type: integer
          example: 500
        amount_per_minute_limit:
          type: integer
          example: 1000000000
        packets_per_minute_limit:
          type: integer
          example: 10
    AccountSettings:
      type: object
      properties:
        ilp_over_http_url:
          type: string
          example: "https://example.com/accounts/our_username_on_peer/ilp"
        ilp_over_http_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_http_outgoing_token:
          type: string
          example: "our_password_on_peer"
        ilp_over_btp_url:
          type: string
          example: "btps://example.com/accounts/our_username_on_peer/ilp/btp"
        ilp_over_btp_incoming_token:
          type: string
          example: "peer_password"
        ilp_over_btp_outgoing_token:
          type: string
          example: "our_password_on_peer"
        settle_threshold:
          type: integer
          example: 1000000000
        settle_to:
          type: integer
          example: 1000000000
    Pairs:
      example: { "ABC": 1.23, "XYZ": 3.25 }
      type: object
      additionalProperties:
        type: number
        example: 1.23
    Routes:
      example: { "example.op1.alice": "alice", "example.op1": "op1" }
      type: object
      additionalProperties:
        type: string
        example: "alice"
    SettlementEngines:
      example:
        { "ABC": "http://localhost:3001", "XYZ": "http://localhost:3002" }
      type: object
      additionalProperties:
        type: string
        example: "http://localhost:3001"