Skip to content

Config API v2 Endpoints

This feature was introduced in Hydrolix v6.2.

The v2 Config API shortens endpoint URLs by removing unnecessary path segments.

Changes in naming pattern⚓︎

The v1 endpoints URLs require 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 available v2 endpoints. See Endpoints table or Config API Openapi.
  2. Convert URL path segment parameters to HTTP body parameters
  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.