Skip to content

Config API v2 Endpoints

This feature was introduced in Hydrolix v6.2.

The Config API supports versioned endpoints. The v2 version of the API

  • is the recommended version for use in Hydrolix v6.4 and later.
  • supports all operations present in the v1 endpoints, with small calling convention changes described in Config API v2 Endpoints.
  • changes endpoints by removing unnecessary path segments, making the URLs shorter.
  • receives all future development effort.

Use the v2 endpoints in all application development

The v1 endpoints remain available and usable after the release of Hydrolix v6.4, but don't support some newer features.

Changes in naming pattern⚓︎

The v1 endpoint URLs required clients to specify all IDs in a hierarchy for all operations, resulting in long URLs with unnecessary IDs.

The v2 endpoints

  • Have shorter names
  • Remove implicit and unnecessary relationships from URL path segments
  • Require only the necessary IDs and accept them as HTTP body parameters
  • Accompany the Config API support for multiple Organizations

Authorization mechanisms remain unchanged

See Authenication and Authorization, especially Acquire authorization tokens.

Conversion steps⚓︎

  1. Identify each v2 endpoint corresponding to the v1 endpoint in use. See Endpoints table or Config API Openapi.
  2. Convert URL path segment parameters to HTTP body parameters, if the calling convention has changed. See Example transform create.
  3. Replace the v1 endpoint with a v2 endpoint.

Example transform create⚓︎

The transform create endpoint illustrates the benefits of the shorter URLs. This command demonstrates using a table with UUID bc6f6d63-a284-4685-a5cf-0544cccf6437.

A new transform, when created, must be attached to a table. The v2 endpoint allows simpler indication of the relationship.

1
2
3
4
5
6
7
8
curl \
  -X POST \
  --data-binary @transform.json \
  --fail-with-body \
  --silent \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${HDX_TOKEN}" \
  -- "${HDX_HYDROLIX_URL}/config/v2/transforms/"
  • Endpoint is /config/v2/transforms/
  • Requires an HTTP body containing the transform table, name, type and all other settings
  • OpenAPI description of Create transform v2

The implicitly related project and organization IDs aren't necessary to create the transform.

1
2
3
4
5
6
7
8
curl \
  -X POST \
  --data-binary @transform.json \
  --fail-with-body \
  --silent \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${HDX_TOKEN}" \
  -- "${HDX_HYDROLIX_URL}/config/v1/orgs/${HDX_ORGID}/projects/${HDX_PROJECTID}/tables/${HDX_TABLEID}/transforms/"
  • Endpoint is /config/v1/orgs/{org_id}/projects/{project_id}/tables/{table_id}/transforms/
  • Requires org_id as a path component
  • Requires project_id as a path component
  • Requires table_id as a path component
  • Requires an HTTP body with the transform name, type, and all other settings
  • Accepts and ignores table if supplied in the HTTP body
  • OpenAPI description of Create transform v1

Relevant payload contents⚓︎

Relevant Payload Contents

This fragmentary payload omits some details of transform settings to highlight the inclusion of table and other required parameters.

1
2
3
4
5
6
7
8
{
  "table": "bc6f6d63-a284-4685-a5cf-0544cccf6437", // (1)!
  "name": "alternate_transform",
  "type": "json",
  "settings": {
    "compression": "gzip, bzip2, zip"
  }
}
  1. The table parameter is required in transform creation v2 endpoints, and accepted and ignored in v1 endpoints, where the table is expected in a path segment.

Full payload⚓︎

Full Payload Example Contents

This is a complete example of a payload used to create a new transform, whether with the v1 or v2 endpoints. See Transform structure for details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "table": "bc6f6d63-a284-4685-a5cf-0544cccf6437", // (1)!
  "name": "alternate_transform",
  "type": "json",
  "settings": {
    "is_default": false,
    "output_columns": [
      {
        "name": "timestamp",
        "datatype": {
          "type": "datetime",
          "primary": true,
          "format": "2006-01-02 15:04:05 MST",
          "resolution": "ms",
          "source": {
            "from_automatic_value": "current_time"
          },
          "suppress": false
        }
      },
      {
        "name": "section",
        "datatype": {
          "type": "string",
          "index": true,
          "suppress": false
        }
      },
      {
        "name": "cciso",
        "datatype": {
          "type": "string",
          "index": true,
          "suppress": false
        }
      },
      {
        "name": "client_ip",
        "datatype": {
          "type": "ip",
          "index": true,
          "suppress": false
        }
      },
      {
        "name": "response_code",
        "datatype": {
          "type": "uint8",
          "index": true,
          "suppress": false
        }
      },
      {
        "name": "response_bytes",
        "datatype": {
          "type": "uint32",
          "index": true,
          "suppress": false
        }
      }
    ],
    "compression": "gzip, bzip2, zip"
  }
}
  1. The table parameter is required in transform creation v2 endpoints, and accepted and ignored in v1 endpoints, where the table is expected in a path segment.