fabric-rest.yaml

# Copyright IBM Corp. All Rights Reserved.
#
# SPDX-License-Identifier: Apache-2.0
#

swagger: '2.0'
info:
  title: DRAFT Hyperledger Fabric REST API
  version: "0.7"
  description: Hyperledger Fabric REST API definition
basePath: /fabric/1_0
schemes: [https]
paths:
##############################################
# LIFECYCLE API end points                   #
##############################################
  /channels/{channelName}/transactions:
    post:
      # description: Commit a transaction, if no proposal responses propose and commit.
      description: Endorse and commit a transaction using configured peers
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: transaction
          in: body
          description: The transaction to commit and any proposal response.
          required: true
          schema:
            $ref: '#/definitions/transactionCommit'
      responses:
        '202':
          description: Response from the orderer or failure responses from peers
          schema:
            $ref: '#/definitions/ordererResponse'
##
#### NOT SUPPORTED
  # /channels/{channelName}/endorse:
  #   post:
  #     description: Send a proposal to the channel's peers. This could be for either chaincode or a transaction.
  #     parameters:
  #       - name: channelName
  #         in: path
  #         description: Name of the channel
  #         required: true
  #         type: string
  #       - name: peers
  #         in: query
  #         description: Peers to send proposal to
  #         required: false
  #         type: array
  #         items:
  #           type: integer
  #       - name: transaction
  #         in: body
  #         description: The proposal.
  #         required: true
  #         schema:
  #           $ref: '#/definitions/transactionProposal'
  #     responses:
  #       '200':
  #         description: Responses from the peers the endorsement request was sent to
  #         schema:
  #           $ref: '#/definitions/proposalResult'
##
  /chaincodes:
    post:
      description: Install chaincode onto the named peers
      parameters:
        - name: peers
          in: query
          description: Peers to install chaincode on
          required: true
          type: array
          items:
            type: integer
        - name: chaincode
          in: body
          description: The chaincode install data.
          required: true
          schema:
            $ref: '#/definitions/ChaincodeInstallRequest'
      responses:
        '200':
          description: Responses from the peers the install request was sent to
          schema:
            $ref: '#/definitions/installResult'
##
  /channels/{channelName}/chaincodes:
    post:
      description: Instantiate new chaincode in the channel for the named peers
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: peers
          in: query
          description: Peers to instantiate chaincode on
          required: true
          type: array
          items:
            type: integer
        - name: chaincode
          in: body
          description: The chaincode instantiate data.
          required: true
          schema:
            $ref: '#/definitions/chaincodeInstantiate'
      responses:
        '202':
          description: Response from the orderer or failure responses from peers
          schema:
            $ref: '#/definitions/ordererResponse'
#
    put:
      description: Instantiate updated chaincode in the channel for the named peers
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: peers
          in: query
          description: Peers to instantiate chaincode on
          required: true
          type: array
          items:
            type: integer
        - name: chaincode
          in: body
          description: The chaincode instantiate data.
          required: true
          schema:
            $ref: '#/definitions/chaincodeInstantiate'
      responses:
        '202':
          description: Response from the orderer or failure responses from peers
          schema:
            $ref: '#/definitions/ordererResponse'
#
    get:
      description: Query all chaincode instantiated on the channel
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
      responses:
        '200':
          description: Returns a ChaincodeQueryResponse
          schema:
            $ref: '#/definitions/ChaincodeQueryResponse'
##############################################
# CHANNEL MANAGEMENT API end points          #
##############################################
  /channels:
    get:
      description: Get the names of known channels from the primary peer
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ChannelQueryResponse'
##
  /channels/{channelName}:
    get:
      description: Get information about the named channel
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/channelInfo'
#
    post:
      description: Create the named channel
      parameters:
        - name: channelName
          in: path
          description: Name of the channel to create
          required: true
          type: string
        - name: channel
          in: body
          description: The contents of a generated channel configuration file encoded in base64
          required: true
          schema:
            $ref: '#/definitions/channel'
      responses:
        '202':
          description: Successful response
          schema:
            $ref: '#/definitions/channelResponse'
#
    put:
      description: Update the named channel
      parameters:
        - name: channelName
          in: path
          description: Name of the channel to update
          required: true
          type: string
        - name: channel
          in: body
          description: The contents of a generated channel configuration file encoded in base64
          required: true
          schema:
            $ref: '#/definitions/channel'
      responses:
        '202':
          description: Successful response
          schema:
            $ref: '#/definitions/channelResponse'
##
  /channels/{channelName}/peers:
    post:
      description: Join a Peer to the channel
      parameters:
        - name: channelName
          in: path
          description: Name of the channel to join the peer to
          required: true
          type: string
        - name: peer
          in: body
          description: The peer information
          required: true
          schema:
            $ref: '#/definitions/peer'
      responses:
        '200':
          description: Successful response from the peer
          schema:
            $ref: '#/definitions/installResult'
##############################################
# QUERY API end points                       #
##############################################
  /channels/{channelName}/transactions/{transactionID}:
    get:
      description: Query a transaction on a channel by ID
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: transactionID
          in: path
          description: The transaction ID to query
          required: true
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ProcessedTransaction'
##
  /channels/{channelName}/blocks:
    get:
      description: Query a block on a channel by ID or Hash
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: blockId
          in: query
          description: Query data
          required: false
          type: integer
        - name: blockHash
          in: query
          description: Query data
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/block'
##
# Query all chaincode defined previously
# /channels/{channelName}/chaincodes:
##
  /channels/{channelName}/chaincodes/{id}:
    get:
      description: Query chaincode instantiated on a channel by ID
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: id
          in: path
          description: Chaincode ID
          required: true
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ChaincodeInfo'
##
  /chaincodes/{id}:
    get:
      description: Query chaincode installed on a peer by ID
      parameters:
        - name: id
          in: path
          description: Chaincode ID
          required: true
          type: string
        - name: peers
          in: query
          description: Peers to query for installed chaincode
          required: true
          type: array
          items:
            type: integer
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ChaincodeInfo'
## Alternate Query ledger style
  /channels/{channelName}/ledger:
    post:
      description: Query the channel's ledger using one of the query parameters
      parameters:
        - name: channelName
          in: path
          description: Name of the channel
          required: true
          type: string
        - name: chaincodeId
          in: query
          description: Chaincode ID to look for
          required: false
          type: string
        - name: blockId
          in: query
          description: Block ID to look for
          required: false
          type: integer
        - name: blockHash
          in: query
          description: Block Hash to look for
          required: false
          type: string
        - name: txnId
          in: query
          description: Transaction ID to look for
          required: false
          type: string
        - name: args
          in: body
          description: Optional args for query by chaincode
          required: false
          schema:
           $ref: '#/definitions/args'
      responses:
        '200':
          description: Successful response containing an object
##
# A rich query to database is not supported by the SDK currently
#
##

#######################################################
# Definitions section                                 #
#######################################################
definitions:
  args:
    description: Array of arguements
    properties:
      fcn:
        type: string
        description: A function name relevant to the chaincode
      args:
        type: array
        description: An array of arguements
        items:
          type: object
    required:
      - args

  block:
    description: The data contained in a Block, ref https://fabric-sdk-node.github.io/global.html#Block
    properties:
      header:
        type: object
        description: The block header
      data:
        type: object
        description: The data contained in the block
      metadata:
        type: object
        description: The metadata for the block

  channel:
    description: The envelope needed to create a Hyperledger Fabric Channel encoded as a base64 string
    properties:
      envelope:
        type: string
        description: The contents of a generated channel configuration file encoded in base64
    required:
      - envelope

  ChannelQueryResponse:
    description: An array of ChannelInfo
    properties:
      channels:
        type: array
        description: An array of Channel names
        items:
          type: object
          properties:
            channel_id:
              type: string
          required:
            - channel_id
    required:
      - channels

  channelResponse:
    description: The response from the channel create or update
    properties:
      status:
        type: string
        description: Has the orderer accepted this request for processing?
      transactionID:
        type: string
        description: The transaction ID used for the request
    required:
      - status
      - transactionID

  ordererResponse:
    description: The response from the orderer
    properties:
      status:
        type: string
        description: The response from the orderer
      transactionID:
        type: string
        description: The transaction ID used for the request
      peerResponses:
        type: array
        description: An array of proposal results if endorsement step failed
        items:
          type: string
    required:
      - transactionID

  installResult:
    description: Array of responses from the peers
    properties:
      peerResponses:
        type: array
        description: An array of ProposalResponse objects, ref https://fabric-sdk-node.github.io/global.html#ProposalResponse
        items:
          type: object
    required:
      - peerResponses

  peer:
    description: Peer information
    properties:
      url:
        type: string
        description: The url of the peer
      opts:
        type: object
        description: The options for the peer
        properties:
          pem:
            type: string
            description: The pem to use with the peer
          ssl-target-name-override:
            type: string
            description: Optional override for use in test environments
        required:
          - pem
    required:
      - url

  transactionProposal:
    description: Transaction proposal
    properties:
      chaincodeId:
        type: string
      args:
        type: array
        description: An array of arguements
        items:
          type: object
      fcn:
        type: string
      # A REST client does not need to create this field, just be told what is used
      # txId:
      #   type: object
      #   description: If not specified for a proposal it will be created dynamically.
    required:
      - chaincodeId
      - args

  transactionCommit:
    # description: Commit a transaction, if proposalResponses empty do endorse first.
    description: Endorse and commit a transaction using configured peers
    properties:
      # proposalResponses:
      #   type: array
      #   description: An array of proposal results from peers
      #   items:
      #     type: object
      proposal:
        $ref: '#/definitions/transactionProposal'
    required:
      - proposal

  channelInfo:
    description: Information about a channel
    properties:
      inputData:
        type: boolean
        description: This is TODO
    required:
      - inputData

  ChaincodeInstallRequest:
    description: Chaincode install details
    properties:
      chaincodePath:
        type: string
      chaincodeId:
        type: string
      chaincodeVersion:
        type: string
      chaincodePackage:
        type: string
        format: byte
        description: Base64 encoded archive file. The archive is expected to be a gzip and must not contain files flagged as executable.
      chaincodeType:
        type: string
    required:
      - chaincodePath
      - chaincodeId
      - chaincodeVersion
      - chaincodePackage

  chaincodeInstantiate:
    description: Chaincode instantiate details
    properties:
      chaincodeId:
        type: string
      chaincodeVersion:
        type: string
      chaincodeType:
        type: string
      fcn:
        type: string
      args:
        type: array
        description: An array of arguements
        items:
          type: object
    required:
      - chaincodeId
      - chaincodeVersion

  ChaincodeQueryResponse:
    description: Array of ChaincodeInfo
    properties:
      chaincodes:
        type: array
        description: An array of ChaincodeInfo
        items:
          $ref: '#/definitions/ChaincodeInfo'
    required:
      - chaincodes

  ChaincodeInfo:
    description: Information about a piece of chaincode
    properties:
      name:
        type: string
      version:
        type: string
      path:
        type: string
      input:
        type: string
      escc:
        type: string
      vscc:
        type: string

  ProcessedTransaction:
    description: Output from querying a transaction
    properties:
      validationCode:
        type: integer
      transactionEnvelope:
        type: object