json_api.yaml

openapi: 3.1.0
info:
  title: XRP Ledger Public API
  description: A JSON RPC API used to query rippled.
  license:
    name: MIT License
    identifier: mit
    url: https://opensource.org/license/mit/
  version: 1.0.0

servers:
  # TODO: Should this list contain non-ripple servers? All UNL ws_urls? Just public infrastructure?
  - url: https://s1.ripple.com:51234
    description: Mainnet Public API server
  # TODO: Should testnet / devnet / xahau / etc. be on this list?
  - url: https://s.altnet.rippletest.net:51234
    description: Testnet (not for production usage)

paths:
  # We use OpenAPI's discriminator field with the `method` name to delineate between the options
  /:
    # TODO: Potentially we can try making a union of types at this level of Request / Response pairs (as opposed to one big Request array, and one big Response array)
    # If that works, we could solve the problem below of tying inputs to outputs very specifically. Needs further investigation.
    post:
      summary: Send JSON-RPC request to server
      requestBody:
        description: JSON-RPC request object
        content:
          application/json:
            schema:
              discriminator:
                propertyName: method
                mapping:
                  account_channels: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsRequest' # TODO: Verify this is the correct syntax
                  account_info: 'requests/account_info_open_api.yaml#/components/schemas/AccountInfoRequest'
                  account_lines: 'requests/account_lines_open_api.yaml#/components/schemas/AccountLinesRequest'
                  submit: 'requests/submit_open_api.yaml#/components/schemas/SubmitRequestV1'
                  ledger_entry: 'requests/ledger_entry_open_api.yaml#/components/schemas/LedgerEntryRequest'
                  # TODO: Add the rest of the JSON RPC requests here
              oneOf:
                - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsRequest'
                - $ref: 'requests/account_info_open_api.yaml#/components/schemas/AccountInfoRequest'
                - $ref: 'requests/account_lines_open_api.yaml#/components/schemas/AccountLinesRequest'
                - $ref: 'requests/submit_open_api.yaml#/components/schemas/SubmitRequestV1'
                - $ref: 'requests/ledger_entry_open_api.yaml#/components/schemas/LedgerEntryRequest'
                # TODO: Add the rest of the JSON RPC requests here
        required: true
      operationId: 'POST'
      responses:
        '200':
          description: JSON-RPC response object
          content:
            application/json:
              schema:
                # TODO: Map the input request types to these output responses.
                # They do not have a consistent field which is available on all of them which tells you which request was sent.
                # Errors have `result.request.method`, but success responses
                # 04/10/24 updates:
                # We cannot do 1:1 mapping between request and response at the moment (probably until OpenAPI 4.0).
                # References: https://github.com/OAI/OpenAPI-Specification/issues/791#issuecomment-1912910995
                oneOf:
                  - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsResponse'
                  - $ref: 'requests/account_info_open_api.yaml#/components/schemas/AccountInfoResponseV1'
                  - $ref: 'requests/submit_open_api.yaml#/components/schemas/SubmitResponseV1'
                  - $ref: 'requests/account_lines_open_api.yaml#/components/schemas/AccountLinesResponse'
                  - $ref: 'requests/ledger_entry_open_api.yaml#/components/schemas/LedgerEntryResponse'
                  # TODO: Add the rest of the JSON RPC responses here

        # TODO: We want to be much more explicit with http error codes for a full implementation of this spec.
        # (Eventually the goal should be removing the '4XX' because all cases are covered)
        # TODO: We also should investigate if some commands in rippled have unique http error codes / responses for common error code
        # which are not shared across commands. (If so they should also be documented here)
        '4XX':
          description: JSON-RPC http error. The response is a plain-text explanation with the http error code and description in the response body.
          content:
            text/plain:
              schema:
                type: string

        '5XX':
          description: JSON-RPC http error. The response is a plain-text explanation with the http error code and description in the response body.
          content:
            text/plain:
              schema:
                type: string

        '503':
          description: An error for when the client is over the server's rate limit.
          content:
            text/plain:
              schema:
                type: string
                enum:
                  - "503 Service Unavailable\n\nServer is overloaded" # TODO: Validate that this is the right string, it's unclear whether 503 is included in the response: https://xrpl.org/rate-limiting.html#json-rpc-rate-limited-error

security: []