Skip to content

ContractAPI

Contract APIs provide generated REST APIs for on-chain smart contracts.

API endpoints are generated to invoke or perform query operations against each of the functions/methods implemented by the smart contract.

API endpoints are also provided to add listeners to the events of that smart contract.

Note that once you have established listeners for your blockchain events into FireFly, you need to also subscribe in your application to receive the FireFly events (of type blockchain_event_received) that are emitted for each detected blockchain event.

For more information see the Events reference section.

URL

The base path for your Contract API is:

  • /api/v1/namespaces/{ns}/apis/{apiName}

For the default namespace, this can be shortened to:

  • /api/v1/apis/{apiName}

FireFly Interface (FFI) and On-chain Location

Contract APIs are registered against:

  1. A FireFly Interface (FFI) definition, which defines in a blockchain agnostic format the list of functions/events supported by the smart contract. Also detailed type information about the inputs/outputs to those functions/events.

  2. An optional location configured on the Contract API describes where the instance of the smart contract the API should interact with exists in the blockchain layer. For example the address of the Smart Contract for an Ethereum based blockchain, or the name and channel for a Hyperledger Fabric based blockchain.

If the location is not specified on creation of the Contract API, then it must be specified on each API call made to the Contract API endpoints.

OpenAPI V3 / Swagger Definitions

Each Contract API comes with an OpenAPI V3 / Swagger generated definition, which can be downloaded from:

  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api/swagger.json

Swagger UI

A browser / exerciser UI for your API is also available on:

  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api

Example

{
    "id": "0f12317b-85a0-4a77-a722-857ea2b0a5fa",
    "namespace": "ns1",
    "interface": {
        "id": "c35d3449-4f24-4676-8e64-91c9e46f06c4"
    },
    "location": {
        "address": "0x95a6c4895c7806499ba35f75069198f45e88fc69"
    },
    "name": "my_contract_api",
    "message": "b09d9f77-7b16-4760-a8d7-0e3c319b2a16",
    "urls": {
        "api": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api",
        "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api/swagger.json",
        "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api"
    },
    "published": false
}

Field Descriptions

Field Name Description Type
id The UUID of the contract API UUID
namespace The namespace of the contract API string
interface Reference to the FireFly Interface definition associated with the contract API FFIReference
location If this API is tied to an individual instance of a smart contract, this field can include a blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel JSONAny
name The name that is used in the URL to access the API string
networkName The published name of the API within the multiparty network string
message The UUID of the broadcast message that was used to publish this API to the network UUID
urls The URLs to use to access the API ContractURLs
published Indicates if the API is published to other members of the multiparty network bool

FFIReference

Field Name Description Type
id The UUID of the FireFly interface UUID
name The name of the FireFly interface string
version The version of the FireFly interface string

ContractURLs

Field Name Description Type
api The URL to use to invoke the API string
openapi The URL to download the OpenAPI v3 (Swagger) description for the API generated in JSON or YAML format string
ui The URL to use in a web browser to access the SwaggerUI explorer/exerciser for the API string