[WIP] OpenAPI support in rippled

[justinr1234]

Currently, the XRP Ledger (rippled) offers an ad-hoc JSON-RPC API. It is implemented in C++ through a variety of headers and function calls. Most of the input / output, parameters, responses, codes - or generally anything - are not documented in code or in spec. The API is manually documented on xrpl.org. See the public API methods reference.

Changes to this interface are picked up manually via people watching pull requests and manually translating this into xrpl.org docs or dependent client libraries such as xrpl.js and xrpl-py. In these dependent places, work is duplicated, and it is error-prone to keep the types in sync as well as bring the libraries in line with the latest changes in rippled.

I would like to propose the creation of an OpenAPI interface that lives within the rippled repo directly, so that enforcement can potentially be done at a code level (during CI/CD testing, compile time static checks, or runtime checking — or a combination of all 3). The existing implementations in the code are good as-is, and should not be overly modified, but instead potentially a new approach could be to automatically generate implementation stubs from the OpenAPI YAML file going forward. The stubs can then be wired up to the existing code, so that everything is backwards compatible.

I propose translating the existing docs and source code into a hand-written OpenAPI file that has good reuse.

(Work In Progress) Proposed file -- Suggest using https://editor.swagger.io/ to view it

openapi: 3.0.0
info:
  title: XRP Ledger Public API
  description: Communicate directly with an XRP Ledger server using the public API methods. Public methods are not necessarily meant for the general public, but they are used by any client attached to the server. Think of public methods as being for members or customers of the organization running the server.
  version: 1.0.0
servers:
  - url: https://s1.ripple.com:51234
    description: XRP Ledger Public API server
paths:
  /:
    post:
      summary: Send JSON-RPC request to server
      requestBody:
        description: JSON-RPC request object
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
        required: true
      operationId: "POST"
      responses:
        "200":
          description: JSON-RPC response object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "400":
          description: JSON-RPC error response object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
components:
  schemas:
    JsonRpcRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
          example: "2.0"
        id:
          type: integer
          example: 1
        method:
          $ref: "#/components/schemas/TransactionType"
        params:
          $ref: "#/components/schemas/TransactionParams"
      required:
        - id
        - method
    JsonRpcResponse:
      type: object
      oneOf:
        - $ref: "#/components/schemas/AccountInfoResponse"
        - $ref: "#/components/schemas/SubmitResponse"
        - $ref: "#/components/schemas/RpcError"
    TransactionType:
      type: string
      enum: [account_info, submit]
    TransactionParams:
      type: array
      items: 
        oneOf:
        - $ref: "#/components/schemas/AccountInfoParams"
        - $ref: "#/components/schemas/SubmitParams"
      discriminator:
        propertyName: method
    AccountInfoParams:
      type: object
      properties:
        account:
          type: string
          example: "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ"
        ledger_hash:
          type: string
          example: "8BB204CE37CFA7A021A16B5F6143400831C4D1779E6FE538D9AC561ABBF4A929"
        ledger_index:
          example: "validated"
          oneOf:
            - type: string
              enum: [validated, current, closed]
              example: validated
            - type: integer
              format: uint32
              example: 61546724
        queue:
          type: boolean
        signer_lists:
          type: boolean
        strict:
          type: boolean
      required:
        - account
    SubmitParams:
      type: object
      properties:
        tx_blob:
          type: string
          example: "1200002280000000240000000561400000000003F8CDB1B5EAC60000000000000000000000A7321034DCA0D17751B4AEBD57CEBC0A0E22A2EC2E0EF1EBF64DD2C5309EEA03E202FD74473045022100EC46A66EB7B6A1B3C4CB4F4CC7F291B4E51D57FBF92F8C1F0E2E2F781DB88AFB02200781B7C15EAF14E4147C10A46CB8F7E9321CCB58172AED6CE37A3199E9D28AFC811475221034DCA0D17751B4AEBD57CEBC0A0E22A2EC2E0EF1EBF64DD2C5309EEA03E202F3145C6D2844630440220136C9E6D8912C19A3C3EE1A8C308EBA5"
    AccountInfoResponse:
      allOf:
        - $ref: "#/components/schemas/RpcResult"
        - type: object
          properties:
            result:
              type: object
              properties:
                account_data:
                  $ref: "#/components/schemas/AccountRoot"
                signer_lists:
                  $ref: "#/components/schemas/SignerList"
                validated:
                  type: boolean
                  example: true
                queue_data: 
                  $ref: "#/components/schemas/QueueData"
              oneOf:
                - properties:
                    ledger_current_index:
                      type: integer
                      example: 71611056
                  required:
                    - ledger_current_index
                - properties:
                    ledger_index:
                      type: integer
                      example: 71611056
                  required:
                    - ledger_index
          required:
            - result
        - not:
            $ref: "#/components/schemas/RpcError"
    SubmitResponse:
      allOf:
        - $ref: "#/components/schemas/RpcResult"
        - type: object
          properties:
            result:
              type: object
              properties:
                engine_result:
                  type: string
                tx_json:
                  type: object
                  example:
                    Account: r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ
                    Amount: 1000
                    Destination: rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh
          required:
            - result
        - not:
            $ref: "#/components/schemas/RpcError"
    AccountRoot:
      type: object
      properties:
        Account:
          type: string
          example: "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
        AccountTxnID:
          type: string
          example: "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D"
        Balance:
          type: string
          example: "148446663"
        BurnedNFTTokens:
          type: integer
          format: uint32
          example: 300
        Domain:
          type: string
          example: "6D64756F31332E636F6D"
        EmailHash:
          type: string
          example: "98B4375E1D753E5B91627516F6D70977"
        Flags:
          type: integer
          format: uint32
          example: 8388608
        LedgerEntryType:
          type: string
          example: "AccountRoot"
        MessageKey:
          type: string
          example: "0000000000000000000000070000000300"
        OwnerCount:
          type: integer
          format: uint32
          example: 3
        PreviousTxnID:
          type: string
          example: "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D"
        PreviousTxnLgrSeq:
          type: integer
          format: uint32
          example: 14091160
        Sequence:
          type: integer
          format: uint32
          example: 336
        TransferRate:
          type: integer
          format: uint32
          example: 1004999999
        index:
          type: string
          example: "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8"
      required:
        - result
        - id
    RpcResult:
      type: object
      properties:
        result:
          type: object
          example: 
            account_data:
              Account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
              AccountTxnID: 7458B6FD22827B3C141CDC88F1F0C72658C9B5D2E40961E45AF6CD31DECC0C29
              Balance: '1039486603'
              Domain: 6D64756F31332E636F6D
              EmailHash: 98B4375E1D753E5B91627516F6D70977
              Flags: 9568256
              LedgerEntryType: AccountRoot
              MessageKey: 0000000000000000000000070000000300
              OwnerCount: 17
              PreviousTxnID: 160426BB861B2E1AD7A4214EE12B41A3C9C4EEBCC15B4D8A5C41E9405E288CDB
              PreviousTxnLgrSeq: 78650349
              RegularKey: rD9iJmieYHn8jTtPjwwkW2Wm9sVDvPXLoJ
              Sequence: 391
              TicketCount: 5
              TransferRate: 4294967295
              index: 13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8
              urlgravatar: 'http://www.gravatar.com/avatar/98b4375e1d753e5b91627516f6d70977'
            ledger_current_index: 79096050
            queue_data:
              txn_count: 0
            validated: false
        id:
          type: integer
          example: 2
      required:
        - result
        - id
    RpcError:
      type: object
      properties:
        error:
          type: string
          example: "actNotFound"
        error_message:
          type: string
          example: "Account not found."
        error_code:
          type: integer
          example: 19
      required:
        - error
    SignerList:
      type: object
      properties:
        Flags:
          type: integer
          format: uint32
          enum: [0, 65536]
          example: 0
        LedgerEntryType:
          type: string
          example: "SignerList"
        OwnerNode:
          type: string
          example: "0000000000000000"
        PreviousTxnID:
          type: string
          example: "5904C0DC72C58A83AEFED2FFC5386356AA83FCA6A88C89D00646E51E687CDBE4"
        PreviousTxnLgrSeq:
          type: integer
          format: uint32
          example: 16061435
        SignerEntries:
          type: array
          items:
            $ref: "#/components/schemas/SignerEntry"
        SignerListID:
          type: integer
          format: uint32
          enum: [0]
          example: 0
        SignerQuorum:
          type: integer
          format: uint32
          example: 3
        index:
          type: string
          example: "A9C28A28B85CD533217F5C0A0C7767666B093FA58A0F2D80026FCC4CD932DDC7"
      required:
        - Flags
        - LedgerEntryType
        - OwnerNode
        - PreviousTxnID
        - PreviousTxnLgrSeq
        - SignerEntries
        - SignerListID
        - SignerQuorum
        - index
    SignerEntry:
      type: object
      properties:
        Account:
          type: string
          example: "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"
        SignerWeight:
          type: integer
          format: uint16
          example: 2
        WalletLocator:
          type: string
          example: "8E6CFA6C4C4CFAD5C81423ED4E23C5FC14F7DCFEBC50DE64579EF41525E3CB079"
      required:
        - Account
        - SignerWeight
    Transaction:
      type: object
      properties:
        auth_change:
          type: boolean
          example: false
        fee:
          type: string
          example: "100"
        fee_level:
          type: string
          example: "2560"
        max_spend_drops:
          type: string
          example: "100"
        seq:
          type: integer
          example: 6
        LastLedgerSequence:
          type: integer
          nullable: true
          example: 10
      required:
        - auth_change
        - fee
        - fee_level
        - max_spend_drops
        - seq
    QueueData:
      type: object
      properties:
        auth_change_queued:
          type: boolean
          example: true
        highest_sequence:
          type: integer
          example: 10
        lowest_sequence:
          type: integer
          example: 6
        max_spend_drops_total:
          type: string
          example: "500"
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          example:
            - auth_change: false
              fee: "100"
              fee_level: "2560"
              max_spend_drops: "100"
              seq: 6
            - LastLedgerSequence: 10
              auth_change: true
              fee: "100"
              fee_level: "2560"
              max_spend_drops: "100"
              seq: 10
        txn_count:
          type: integer
          example: 5
      required:
        - auth_change_queued
        - highest_sequence
        - lowest_sequence
        - max_spend_drops_total
        - transactions
        - txn_count

[Tokeiito]

awesome idea. having automated openapi documentation would be super helpful especially from automated testing perspective. Especially for new features.