Documentation
ProductPricingDocsBlog

Intro to Config API

Introduction to the primary Hydrolix application configuration API

Suggest Edits

Overview

The Hydrolix Config API offers control over Projects and Tables, Data Source Configuration, Dictionaries, Functions, Query Options, and many other functions of the Hydrolix cluster.

Use the Config API for controlling the Hydrolix cluster. Consult the Open API reference for details of specific API endpoints.

This page provides an introduction to some common patterns used by the Config API.

Authentication and authorization

Users authenticate to the Config API using the same authentication mechanisms supported for all APIs in the cluster. See User Authentication.

The Config API supports a fine-grained role based access control (RBAC) system. The RBAC system allows administrators to control authorized activity by managing users, roles, policies, permissions, and scopes.

An Audit Logging system produces a record of user activity.

How to use an auth token

User accounts can use the login API endpoint to acquire an auth token.

Acquire auth token

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER and $HDX_PASSWORD environment variables:

export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

Present auth token

After assigning an auth token to $HDX_TOKEN, use the following endpoint in the Config API.

curl --header "Authorization: Bearer $HDX_TOKEN" \
  -- https://docs-sandbox.hydrolix.dev/config/v1/users/current | jq .

If the token is valid, the Config API returns an HTTP 200 and an informational block describing the user.

{
  "uuid": "531ec32e-952c-425f-8349-064807aec521",
  "email": "[email protected]",
  "orgs": [
    {
      "uuid": "db7cddc1-36fc-49df-b1fb-5a205b9611d8",
      "name": "Hydrolix",
      "type": "singletenant",
      "cloud": "aws",
      "kubernetes": true
    }
  ],
  "is_superuser": false,
  "roles": [
    "super_admin"
  ],
  "audit": false,
  "emailVerified": true,
  "enabled": true,
  "is_service_account": false,
  "name": "[email protected]"
}

If the token is invalid, the Config API returns an HTTP 401 and the following error.

{
  "detail": "Invalid authentication credentials provided."
}

Common patterns

The Config API implements REST conventions. The published Open API reference describes API behavior.

Pagination

The Config API supports fully-featured, consistent pagination across endpoints starting in Hydrolix v5.4.

Two patterns of pagination are in use

  • Page number for resources managed by most endpoints
  • Cursor style for catalog and data management, endpoints that can return millions of objects

For catalog and partition management endpoints, which can track millions of objects, a cursor-style pagination is necessary. These endpoints are primarily used inside the cluster for data management.

Page number

Most endpoints in the Config API for managing resources use the common industry pattern of page number pagination. In each request, API clients request one page of results and communicate both the page size and page number to the server.

Page number pagination is used for all objects with unbounded size. These resources are always returned in paginated responses.

Requests can include HTTP query parameters page (default 1) and page_size (default 100, maximum 1000).

Page numbers begin at page 1, which is why the default is 1.

An example request: /config/v1/users/?page=2&page_size=300

This example annotated response shows the results returned by Hydrolix, now including important pagination context:

{
  "results": [ ... ],    # Array of items
  "count": int,          # total records
  "current": int,        # this page num
  "num_pages": int,      # total pages
  "next": int,           # next page number or 0 if no next
  "previous": int,       # prev page number or 0 if no prev
}

Cursor style

All catalog and partition management endpoints use cursor pagination. These endpoints are crucial for managing the catalog and interacting with the underlying Hydrolix data storage.

The first request to any endpoint supporting cursor pagination should omit the cursor query parameter. Subsequent requests can set the cursor to the value in the next or previous to move through the result set. The page_size controls the maximum number of results in the response.

All requests can include the page_size (default 1000, max 10000) HTTP query parameter. After the first request, subsequent requests must include HTTP query parameter cursor. The cursor value indicates position and direction in the result set. Example:

/config/v1/orgs/:org_id/catalog/?page_size=4000&cursor=XYZ

Responses look like this:

{
  "results": [ ... ],    # Array of items
  "next":     string,    # next page link or None if no next page
  "previous": string,    # prev page link or None if no previous page
}

Cursors are opaque Base64-encoded strings. If the value of previous is cj0xJnA9NDg3, then supplying query parameters like cursor=cj0xJnA9NDg3 return the previous set of results.

OpenAPI reference

The Config API Open API reference offers implementers details of the API.

Updated 9 days ago