API Oracle

Connecting to any API with Chainlink enables your contracts to access to any external data source through our decentralized oracle network. We understand making smart contracts compatible with off-chain data adds to the complexity of building smart contracts.

Whether your contract requires sports results, the latest weather, or any other publicly available data, the Chainlink contract library provides the tools required for your contract to consume it.

Chainlink Any API Documentation | Chainlink DocumentationChainlink Documentation

DATUM only Support GET requests with uint responses currently , in the test phase

Response Types

Make sure to choose an oracle job that supports the data type that your contract needs to consume. Multiple data types are available such as:

• uint256 - Unsigned integers

• int256 - Signed integers

• bool - True or False values

• string - String

• bytes32 - Strings and byte values. If you need to return a string, use bytes32. Here’s one method of converting bytes32 to string. Currently, any return value must fit within 32 bytes. If the value is bigger than that, make multiple requests.

• bytes - Arbitrary-length raw byte data

There are multiple way of responses supported like :

• Single Word Responses

• Multi Word Responses

• Array Responses

• Large Responses

Make a GET Request | Chainlink DocumentationChainlink Documentation

This guide explains how to make an HTTP GET request to an external API from a smart contract using Chainlink’s Request & Receive Data cycle and receive a single response.

Using API Oracle

• First step it to figure out the JobID of the API request you wanna make , more info that can be found below depending on the type of request and response

Testnet Oracles | Chainlink DocumentationChainlink Documentation

• Next for interacting with the contracts , install datum-contract and import them as follow

// SPDX-License-Identifier: AGPL-3.0-only
pragma solidity ^0.8.14;

import "datum-contracts/interfaces/APIOracleInterface.sol";

• Creating the contract instance with the oracle Address for the chain you are working with

    oracleAddress = 0x25d5298617C53cA2E4f4BAB91Ee3D4FF37Ac05F6
    
    APIOracleInterface _apiOracle =
        APIOracleInterface(oracleAddress);

• Defining the jobID which you have decided , Here we are doing GET requests returning uint

    bytes32 jobId = "ca98366cc7314957b8c012c72f05aeeb";

Check if there is a req built for your JobId by calling buildAPIRequest , if it returns a non default response , meaning there is a request built already ,

Either Call requestBuildReq , and the Oracle will build one for you , as follow

    function requestJob(bytes32 _jobId) public {
        _apiOracle.requestBuildReq(_jobId);
    }

• Now we need to construct our request with the API Call we wanna perform , as follow

    function requestAPIData() public {
        //Build API Request First , check if the request
        req = _apiOracle.buildAPIRequest(jobId);

        // Now we need to add the path and the info , to build the Request
        req.add(
            "get",
            "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD"
        );

        req.add("path", "RAW,ETH,USD,VOLUME24HOUR"); // Chainlink nodes 1.0.0 and later support this format

        // Multiply the result by 1000000000000000000 to remove decimals
        int256 timesAmount = 10 ** 18;
        req.addInt("times", timesAmount);

        apiId = _apiOracle.sendRequest(req);
    }

The Most important part is to perfectly build the req , by adding all the parameters like , type of req , API Link , response path , and response Customisation Detailed guide on how to create the req method can be found on Chainlink Docs , there are various examples of different API requests being made

• In the backend , the tasks will be performed and the response will be stored back in the Oracle , which can be queried again as follow :

    function getResult() public view returns (uint) {
        return _apiOracle.getRequestData(apiId);
    }

Full Contracts

// SPDX-License-Identifier: AGPL-3.0-only
pragma solidity ^0.8.14;

// *************************************
// *    Minimum Viable API Oracle  *
// *************************************

// This contract shows how to get up and running as quickly as posible with Chainlink's VRF oracle
// We will requestRandomness from the oracle and fetch it later

import "datum-contracts/interfaces/APIOracleInterface.sol";

contract APIOracleTest {
    APIOracleInterface _apiOracle =
        APIOracleInterface(0x25d5298617C53cA2E4f4BAB91Ee3D4FF37Ac05F6);

    uint apiId;
    bytes32 jobId = "ca98366cc7314957b8c012c72f05aeeb";

    // Submit a random uint request to the Oracle
    // Check if the req exists for the JobID
    // List of the JobIDs could be found here : https://docs.chain.link/any-api/testnet-oracles/#jobs
    function requestAPIData() public {
        //Build API Request First , check if the request
        req = _apiOracle.buildAPIRequest(jobId);

        // Now we need to add the path and the info , to build the Request
        req.add(
            "get",
            "https://min-api.cryptocompare.com/data/pricemultifull?fsyms=ETH&tsyms=USD"
        );

        req.add("path", "RAW,ETH,USD,VOLUME24HOUR"); // Chainlink nodes 1.0.0 and later support this format

        // Multiply the result by 1000000000000000000 to remove decimals
        int256 timesAmount = 10 ** 18;
        req.addInt("times", timesAmount);

        apiId = _apiOracle.sendRequest(req);
    }

    // Only in Case the JobId req is not there
    function requestJob(bytes32 _jobId) public {
        _apiOracle.requestBuildReq(_jobId);
    }

    // Fetch the Result for the API requests
    function getResult() public view returns (uint) {
        return _apiOracle.getRequestData(apiId);
    }
}

Extra API req Examples

Weather Data

Job ids can be found here

 function requestAvgTemp(string memory _from, string memory _to) external {
        Chainlink.Request memory req = buildChainlinkRequest(
            avgTempJobId,
            address(this),
            this.fulfillAvgTemp.selector
        );
        req.add("dateFrom", _from);
        req.add("dateTo", _to);
        req.add("method", "AVG");
        req.add("column", "temp");
        sendChainlinkRequest(req, fee);
    }

 function requestTotalRain(string memory _from, string memory _to) external {
        Chainlink.Request memory req = buildChainlinkRequest(
            totalRainJobId,
            address(this),
            this.fulfillTotalRain.selector
        );
        req.add("dateFrom", _from);
        req.add("dateTo", _to);
        req.add("method", "SUM");
        req.add("column", "prcp");
        sendChainlinkRequest(req, fee);
    }

   function requestHail(string memory _from, string memory _to) external {
        Chainlink.Request memory req = buildChainlinkRequest(
            hailJobId,
            address(this),
            this.fulfillHail.selector
        );
        req.add("dateFrom", _from);
        req.add("dateTo", _to);
        req.add("method", "SUM");
        req.add("column", "hail");
        sendChainlinkRequest(req, fee);
    }

With these simple steps , we can use Chainlink's API Oracle to fetch off chain data on chain in a decentralized manner