OpenAPISpecification.yaml

# Copyright 2017 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ------------------------------------------------------------------------------

    swagger: '2.0'

    info:
      version: "0.8.0"
      title: Sawtooth REST API
      description: |
        _This HTTP pragmatic REST API is built on top of Sawtooth's
        existing ZMQ/Protobuf infrastructure, simplifying client
        interaction with the blockchain by exposing endpoints that
        use common HTTP/JSON standards._
    host: localhost:8008
    paths:
      /batches:
        post:
          summary: Sends a BatchList to the validator
          description: |
            Accepts a protobuf formatted `BatchList` as an octet-stream binary
            file and submits it to the validator to be committed.
            The API will return immediately with a status of `202`. There will be
            no `data` object, only a `link` to a `/batch_statuses` endpoint to be
            polled to check the status of submitted batches.
          consumes:
            - application/octet-stream
          parameters:
            - name: BatchList
              in: body
              description: A binary encoded protobuf BatchList
              schema:
                $ref: "#/definitions/BatchList"
              required: true
          responses:
            202:
              description: Batches submitted for validation, but not yet committed
              schema:
                properties:
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            429:
              $ref: "#/responses/429TooManyRequests"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
        get:
          summary: Fetches a list of batches
          description: >
            Fetches a paginated list of batches from the validator.
          parameters:
            - $ref: "#/parameters/head"
            - $ref: "#/parameters/start"
            - $ref: "#/parameters/limit"
            - $ref: "#/parameters/reverse"
          responses:
            200:
              description: Successfully retrieved batches
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/definitions/Batch"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
                  paging:
                    $ref: "#/definitions/Paging"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /batches/{batch_id}:
        parameters:
          - $ref: "#/parameters/batch_id"
        get:
          summary: Fetches a particular batch
          responses:
            200:
              description: Successfully retrieved batch
              schema:
                properties:
                  data:
                    $ref: "#/definitions/Batch"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            404:
              $ref: "#/responses/404NotFound"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /batch_statuses:
        get:
          summary: Fetches the committed statuses for a set of batches
          description: |
            Fetches an array of objects with a status and id for each batch
            requested. There are four possible statuses with string values
            `'COMMITTED'`, `'INVALID'`, `'PENDING'`, and `'UNKNOWN'`.
            The batch(es) you want to check can be specified using the `id` filter
            parameter. If a `wait` time is specified in the URL, the API will wait
            to respond until all batches are committed, or the time in seconds has
            elapsed. If the value of `wait` is not set (i.e., `?wait&id=...`), or
            it is set to any non-integer value other than `false`, the wait time
            will be just under the API's specified timeout (usually 300).
            Note that because this route does not return full resources, the
            response will not be paginated, and there will be no `head` or
            `paging` properties.
          parameters:
            - name: id
              in: query
              description: A comma-separated list of batch ids
              type: string
              required: true
            - $ref: "#/parameters/wait"
          responses:
            200:
              description: Successfully retrieved statuses
              schema:
                properties:
                  data:
                    $ref: "#/definitions/BatchStatuses"
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
        post:
          summary: Fetches the committed statuses for a set of batches
          description: |
            Identical to `GET /batch_statuses`, but takes ids of batches as a JSON
            formatted POST body rather than a query parameter. This allows for many
            more batches to be checked and should be used for more than 15 ids.
            Note that because query information is not encoded in the URL, no `link`
            will be returned with this query.
          consumes:
            - application/json
          parameters:
            - name: Batch Ids
              in: body
              description: A JSON array of batch id strings
              required: true
              schema:
                type: array
                items:
                  type: string
                  example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
            - $ref: "#/parameters/wait"
          responses:
            200:
              description: Successfully retrieved statuses
              schema:
                properties:
                  data:
                    $ref: "#/definitions/BatchStatuses"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /state:
        get:
          summary: Fetches the data for the current state
          description: >
            Fetches a paginated list of entries for the current state, or relative
            to a particular head block. Using the `address` filter parameter will
            narrow the list to any entries that have an address beginning with the
            characters specified.
            Note that the partial address in `address` parameter should have even 
            number of hexadecimal characters (i.e., complete bytes).
            
          parameters:
            - $ref: "#/parameters/head"
            - name: address
              in: query
              type: string
              description: A partial address to filter leaves by
            - $ref: "#/parameters/start"
            - $ref: "#/parameters/limit"
            - $ref: "#/parameters/reverse"
          responses:
            200:
              description: Successfully retrieved state data
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/definitions/Entry"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
                  paging:
                    $ref: "#/definitions/Paging"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /state/{address}:
        parameters:
          - $ref: "#/parameters/address"
        get:
          summary: Fetches a particular leaf from the current state
          description: >
            Takes full 70-character address and fetches a particular leaf.
            For partial address (i.e., group of leaves) use `/state` above. 
          parameters:
            - $ref: "#/parameters/head"
          responses:
            200:
              description: Successfully fetched leaves
              schema:
                properties:
                  data:
                    type: string
                    format: byte
                    example: Zm9vOmJhcg==
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            404:
              $ref: "#/responses/404NotFound"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /blocks:
        get:
          summary: Fetches a list of blocks
          description: >
            Fetches a paginated list of blocks from the validator.
          parameters:
            - $ref: "#/parameters/head"
            - $ref: "#/parameters/start"
            - $ref: "#/parameters/limit"
            - $ref: "#/parameters/reverse"
          responses:
            200:
              description: Successfully retrieved blocks
              schema:
                properties:
                  data:
                    type: array
                    items:
                      - $ref: "#/definitions/Block"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
                  paging:
                    $ref: "#/definitions/Paging"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /blocks/{block_id}:
        parameters:
          - $ref: "#/parameters/block_id"
        get:
          summary: Fetches a particular block
          responses:
            200:
              description: Successfully retrieved block
              schema:
                properties:
                  data:
                    $ref: "#/definitions/Block"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
    
            400:
              $ref: "#/responses/400BadRequest"
            404:
              $ref: "#/responses/404NotFound"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /transactions:
        get:
          summary: Fetches a list of transactions
          description: >
            Fetches a paginated list of transactions from the validator.
          parameters:
            - $ref: "#/parameters/head"
            - $ref: "#/parameters/start"
            - $ref: "#/parameters/limit"
            - $ref: "#/parameters/reverse"
          responses:
            200:
              description: Successfully retrieved transactions
              schema:
                properties:
                  data:
                    type: array
                    items:
                      - $ref: "#/definitions/Transaction"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
                  paging:
                    $ref: "#/definitions/Paging"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /transactions/{transaction_id}:
        parameters:
          - $ref: "#/parameters/transaction_id"
        get:
          summary: Fetches a particular transaction
          responses:
            200:
              description: Successfully retrieved transaction
              schema:
                properties:
                  data:
                    $ref: "#/definitions/Block"
                  head:
                    $ref: "#/definitions/Head"
                  link:
                    $ref: "#/definitions/Link"
    
            400:
              $ref: "#/responses/400BadRequest"
            404:
              $ref: "#/responses/404NotFound"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /receipts:
        get:
          summary: Fetches the receipts for a set of transactions
          description: |
            Fetches an array of objects for each receipt requested.
            The receipt(s) you want to retrieve can be specified using the `id`
            filter parameter, where `id` refers to the transaction id of the
            transaction the receipt is associated with.
          parameters:
            - name: id
              in: query
              description: A comma-separated list of transaction ids
              type: string
              required: true
          responses:
            200:
              description: Successfully retrieved transaction receipts
              schema:
                properties:
                  data:
                    $ref: "#/definitions/TransactionReceipts"
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
        post:
          summary: Fetches the receipts for a set of transactions
          description: |
            Identical to `GET /receipts`, but takes ids of transactions as a JSON
            formatted POST body rather than a query parameter. This allows for many
            more receipts to be fetched and should be used with more than 15 ids.
            Note that because query information is not encoded in the URL, no `link`
            will be returned with this request.
          consumes:
            - application/json
          parameters:
            - name: Transaction Ids
              in: body
              description: A JSON array of transaction id strings
              required: true
              schema:
                type: array
                items:
                  type: string
                  example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
            - $ref: "#/parameters/wait"
          responses:
            200:
              description: Successfully retrieved transaction receipts
              schema:
                properties:
                  data:
                    $ref: "#/definitions/TransactionReceipts"
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /peers:
        get:
          summary: Fetches the endpoints of the authorized peers of the validator
          responses:
            200:
              description: Successfully retrieved peers
              schema:
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      example: tcp://12.345.67.890:8800
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
      /status:
        get:
          summary: Fetches information pertaining to the status of the validator
          responses:
            200:
              description: Successfully retrieved status
              schema:
                properties:
                  data:
                    type: object
                    properties:
                      endpoint:
                        type: string
                        example: tcp://12.345.67.890:8800
                      peers:
                        type: array
                        items:
                          type: object
                          properties:
                            endpoint:
                              type: string
                              example: tcp://12.345.67.890:8800
                  link:
                    $ref: "#/definitions/Link"
            400:
              $ref: "#/responses/400BadRequest"
            500:
              $ref: "#/responses/500ServerError"
            503:
              $ref: "#/responses/503ServiceUnavailable"
    
    responses:
      400BadRequest:
        description: Request was malformed
        schema:
          $ref: "#/definitions/Error"
      404NotFound:
        description: Address or id did not match any resource
        schema:
          $ref: "#/definitions/Error"
      429TooManyRequests:
        description: Too many requests have been made to process batches
        schema:
          $ref: "#/definitions/Error"
      500ServerError:
        description: Something went wrong within the validator
        schema:
          $ref: "#/definitions/Error"
      503ServiceUnavailable:
        description: API is unable to reach the validator
        schema:
          $ref: "#/definitions/Error"
    
    parameters:
      address:
        name: address
        in: path
        type: string
        required: true
        description: Radix address of a leaf
      block_id:
        name: block_id
        in: path
        type: string
        required: true
        description: Block id
      batch_id:
        name: batch_id
        in: path
        type: string
        required: true
        description: Batch id
      transaction_id:
        name: transaction_id
        in: path
        type: string
        required: true
        description: Transaction id
      head:
        name: head
        in: query
        type: string
        default: latest
        description: Index or id of head block
      wait:
        name: wait
        in: query
        type: integer
        description: A time in seconds to wait for commit
      limit:
        name: limit
        in: query
        type: integer
        default: 1000
        description: Number of items to return
      start:
        name: start
        in: query
        type: string
        description: Id to start paging (inclusive)
      reverse:
        name: reverse
        in: query
        type: string
        description: If the list should be reversed
    
    definitions:
      Head:
        type: string
        example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
      Link:
        type: string
        example: https://api.sawtooth.com/state?head=65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
      Paging:
        properties:
          start:
            type: string
            example: "65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd"
          limit:
            type: integer
            example: 54321
          next_position:
            type: string
            example: "65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd"
          next:
            type: string
            example: https://api.sawtooth.com/state?head=65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd&start=2000&limit=1000
    
      Error:
        properties:
          code:
            type: integer
            example: 34
          title:
              type: string
              example: No Batches Submitted
          message:
            type: string
            example: >
              The protobuf BatchList you submitted was empty and contained no
              Batches. You must submit at least one Batch.
      BatchStatuses:
        type: array
        items:
          properties:
            id:
              type: string
              example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
            status:
              type: string
              example: INVALID
              enum:
                - COMMITTED
                - INVALID
                - PENDING
                - UNKNOWN
            invalid_transactions:
              type: array
              items:
                properties:
                  id:
                    type: string
                    example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
                  message:
                    type: string
                    example: Verb is \"inc\" but name \"foo\" not in state
                  extended_data:
                    type: string
                    format: byte
                    example: ZXJyb3IgZGF0YQ==
    
      Entry:
        properties:
          address:
            type: string
            example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
          data:
            type: string
            format: byte
            example: Zm9vOmJhcg==
    
      TransactionHeader:
        properties:
          batcher_public_key:
            type: string
            example: 02d260a46457a064733153e09840c322bee1dff34445d7d49e19e60abd18fd0758
          dependencies:
            type: array
            items:
              type: string
              example: 1baee350bdb60bcee60e3d325d43283cf830b4c23b2cb17d3bb43935bd7af3761c2bee79847c72a9e396a9ae58f48add4e43f94eb83f84442c6085c1dd5d4dbe
          family_name:
            type: string
            example: intkey
          family_version:
            type: string
            example: "1.0"
          inputs:
            type: array
            items:
              type: string
              example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
          nonce:
            type: string
            example: QAApS4L
          outputs:
            type: array
            items:
              type: string
              example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
          payload_sha512:
            type: string
            example: fb6135ef73f4fe77367f9384b3bbbb158f4b8603c9d612157108e5c271868fce2242ee4abd7a29397ba63780c3ccab13783dfd4d9f0167beda03cdb0e37b87f4
          signer_public_key:
            type: string
            example: 038bba5708acc262464c9fe30d3de9e905a9a5fa30cedd151dd9cd09ea26d46d00
      Transaction:
        properties:
          header:
            $ref: "#/definitions/TransactionHeader"
          header_signature:
            type: string
            example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
          payload:
            type: string
            format: binary
    
      TransactionReceipt:
        properties:
          transaction_id:
            type: string
            example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
          state_changes:
            type: array
            items:
              properties:
                type:
                  type: string
                  example: SET
                address:
                  type: string
                  example: 1cf12650d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c
                value:
                  type: string
                  format: binary
          events:
            type: array
            items:
              properties:
                event_type:
                  type: string
                  example: sawtooth/block-commit
                attributes:
                  type: array
                  items:
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                data:
                  type: string
                  format: binary
          data:
            type: array
            items:
              type: string
              format: binary
      TransactionReceipts:
        type: array
        items:
          - $ref: "#/definitions/TransactionReceipt"
    
      BatchHeader:
        properties:
          signer_public_key:
            type: string
            example: 038bba5708acc262464c9fe30d3de9e905a9a5fa30cedd151dd9cd09ea26d46d00
          transaction_ids:
            type: array
            items:
              type: string
              example: 540a6803971d1880ec73a96cb97815a95d374cbad5d865925e5aa0432fcf1931539afe10310c122c5eaae15df61236079abbf4f258889359c4d175516934484a
      Batch:
        properties:
          header:
            $ref: "#/definitions/BatchHeader"
          header_signature:
            type: string
            example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
          transactions:
            type: array
            items:
              $ref: "#/definitions/Transaction"
      BatchList:
        properties:
          batches:
            type: array
            items:
              $ref: "#/definitions/Batch"
    
      BlockHeader:
        properties:
          block_num:
            type: integer
            example: 12345
          previous_block_id:
            type: string
            example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
          signer_public_key:
            type: string
            example: 02d260a46457a064733153e09840c322bee1dff34445d7d49e19e60abd18fd0758
          batch_ids:
            type: array
            items:
              type: string
              example: 89807bfc9089e37e00d87d97357de14cfbc455cd608438d426a625a30a0da9a31c406983803c4aa27e1f32a3ff61709e8ec4b56abbc553d7d330635b5d27029c
          consensus:
            type: string
            format: binary
          state_root_hash:
            type: string
            example: 708ca7fbb701799bb387f2e50deaca402e8502abe229f705693d2d4f350e1ad6
      Block:
        properties:
          header:
            $ref: "#/definitions/BlockHeader"
          header_signature:
            type: string
            example: 65cd3a3ce088b265b626f704b7f3db97b6f12e848dccb35d7806f3d0324c71b709ed360d602b8b658b94695374717e3bdb4b76f77886953777d5d008558247dd
          batches:
            type: array
            items:
              $ref: "#/definitions/Batch"