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:

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.
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`