Skip to main content

Integrating Clients with Datasets

The following is a guide on integrating 3rd-party applications/clients with your Fluree dataset.

Overview​

To connect an external client to a Nexus dataset, you'll first need to use the Settings UI for your dataset to generate an API Key.

info

API Keys can be configured with different policy groups / permissions. Be thoughtful about the level of access you grant to your API Keys.

For more information on generating and managing API Keys, you can read the documentation about API Keys here.

The UI for generating a new API key

Using an API Key​

API Keys can be used in the Authorization header of HTTP requests to authenticate against the Fluree Cloud Platform's API.

A simple example of using an API Key to query a dataset would look like this:


curl --location 'https://dev.flur.ee/fluree/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: 7G5ka...vtlq5g' \
--data '{
"from": "fluree-jld/387028092977716",
"where": {
"@id": "?id",
"@type": "Yeti"
},
"select": { "?id": ["@type", "age", "name", "verified"] }
}'

info

Besides the query itself, the two important parts of this request are...

  1. The Authorization header, the value of which is simply the API Key you generated.
  2. The from clause of the query (or the ledger clause of a transaction), which is the name of your dataset (e.g. fluree-jld/387028092977716). You can find this value on the Query or Notebooks section for your dataset.

The following Javascript examples show what using an API Key would look like:

Query​


import fetch from "node-fetch";
const datasetID = `<DATASET-ID-HERE>`;
const APIKey = `<API-KEY-HERE>`;
const query = {
from: datasetID,
select: { "http://example.org/andrew": ["*"] },
};
const url = "https://data.flur.ee/fluree/query"; // notice we use /query here
const headers = {
"Content-Type": "application/json",
Authorization: APIKey,
};
try {
const resp = await fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(query),
});
const data = await resp.json();
console.log(data);
} catch (error) {
console.error(error);
}

Transact​


import fetch from "node-fetch";
const datasetID = `<DATASET-ID-HERE>`;
const APIKey = `<API-KEY-HERE>`;
const transaction = {
ledger: datasetID,
insert: { "@id": "http://example.org/andrew", "@type": "Person" },
};
const url = "https://data.flur.ee/fluree/transact"; // notice we use /transact here
const headers = {
"Content-Type": "application/json",
Authorization: APIKey,
};
try {
const resp = await fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(transaction),
});
const data = await resp.json();
console.log(data);
} catch (error) {
console.error(error);
}

Example Application​

The following is a simple example of a React application that uses an API Key to query a dataset.

You can run the app (and view the source code) directly in your browser by clicking the Stackblitz link below, or you can visit the GitHub repo to clone and run the example application locally:

Open in StackBlitz Open in GitHub