API: Getting Started

Suggest Edits

To get started using the io.vault API, you first need to obtain an API key. Here's how:

  1. Log in to the io.vault web dashboard at https://app.iofinnet.com
  2. Navigate to the Settings page
  3. Under the API Keys section, click "Create New API Key"
  4. Give your API key a name and description
  5. Select the permissions you want to grant to this API key
  6. Click "Create API Key"
  7. Securely store the API key, as you will not be able to view it again

Your API key will be a long string of characters, and will be presented with an ID, something like:

  • Client ID: 5b65883a-51e3-446d-b109-776c5649e579
  • Client Secret: Px7&nKFKx8vcjxeief256wX&n2D_zISe3ER2GYKhAd...

Keep both of these values safe, as you will use them later to retrieve an access token for the API.

Making Queries and Mutations with the io.vault API

The io.vault API is built on GraphQL, which allows you to precisely request the data you need and make changes to your vaults and transactions.

To make a request to the API, you'll send a POST request to the /graphql endpoint with a JSON payload containing your query or mutation.

Here's an example query to retrieve a list of your vaults:

Keep this API key secure, as it grants access to perform actions on your io.vault account based on the permissions you assigned.

In the next section, we'll look at how to use this API key to authenticate requests to the io.vault GraphQL API.

Error Handling with the io.vault API

When making requests to the io.vault API, it's important to handle errors gracefully. There are a several types of errors you may encounter.

If there's a problem with the request itself, such as an authentication error or a server error, you'll receive a non-200 HTTP status code.

For example, if you forget to include your API key, you'll get a 401 Unauthorized response:

{
  "message": "Unauthorized"
}

There may be a problem with the network connection, such as a timeout or a DNS failure. In this case, for example, the fetch promise will reject with a TypeError.

Here's an example of how you might call the API and handle any returned errors in TypeScript:

async function fetchFromApi(query: string, variables?: Record<string, any>) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.IO_VAULT_API_KEY}`,
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });

    const json = await response.json();

    if (response.ok) {
      if (json.errors) {
        throw new Error(JSON.stringify(json.errors));
      }
      return json.data;
    } else {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
  } catch (err) {
    if (err instanceof TypeError) {
      throw new Error(`Network error: ${err.message}`);
    } else {
      throw err;
    }
  }
}

This function throws a descriptive error for GraphQL errors, HTTP errors, and network errors, which you can catch and handle in your calling code.

GraphQL Errors

If there's a problem with your GraphQL query, such as a syntax error or an invalid field name, the server will return a 200 OK response with an errors array in the JSON payload.

For example:

  vaults(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

The first argument specifies the maximum number of results to return. The after argument is a cursor that specifies where to start in the list.

The query returns an object with an edges array and a pageInfo object. Each edge contains a node (the actual vault object) and a cursor that you can use for subsequent requests. The pageInfo contains a hasNextPage boolean indicating if there are more results, and an endCursor that you can use for the next page.

To retrieve the next page, you would make the same query but pass the endCursor as the after argument.

Filtering

Many queries also support filtering arguments to narrow down the results.

For example, to retrieve only vaults with a specific status:

query {
  vaults(where: { status: CREATED }) {
    id
    name
    status
  }
}

Or to retrieve transactions within a certain date range:

query {
  transactions(
    where: {
      createdAt_gte: "2023-01-01T00:00:00Z"
      createdAt_lte: "2023-12-31T23:59:59Z"
    }
  ) {
    id
    status
    amount
    createdAt
  }
}

Consult the API reference documentation for the available filtering options for each query.

In the next section, we'll look at how to handle errors when making API requests.

Pagination and Filtering with the io.vault API

Many of the queries in the io.vault API support pagination and filtering to help you efficiently retrieve the data you need.

Pagination

Pagination allows you to retrieve a subset of a large list of results. It uses a cursor-based approach.

Updated 2 months ago