Add examples to Reference Tables API documentation

features/v2/reference_tables.feature

@@ -24,7 +24,7 @@ Feature: Reference Tables
   @generated @skip @team:DataDog/redapl-experiences
   Scenario: Create reference table upload returns "Bad Request" response
     Given new "CreateReferenceTableUpload" request
-    And body with value {"data": {"attributes": {"headers": [""], "part_count": 3, "part_size": 10000000, "table_name": ""}, "type": "upload"}}
+    And body with value {"data": {"attributes": {"headers": ["field_1", "field_2"], "part_count": 3, "part_size": 10000000, "table_name": ""}, "type": "upload"}}
     When the request is sent
     Then the response status is 400 Bad Request
 
@@ -108,14 +108,14 @@ Feature: Reference Tables
   Scenario: Update reference table returns "Bad Request" response
     Given new "UpdateReferenceTable" request
     And request contains "id" parameter from "REPLACE.ME"
-    And body with value {"data": {"attributes": {"description": "this is a cloud table generated via a cloud bucket sync", "file_metadata": {"access_details": {"aws_detail": {"aws_account_id": "test-account-id", "aws_bucket_name": "test-bucket", "file_path": "test_rt.csv"}}, "sync_enabled": true}, "schema": {"fields": [{"name": "id", "type": "INT32"}, {"name": "name", "type": "STRING"}], "primary_keys": ["id"]}, "sync_enabled": false, "tags": ["test_tag"]}, "id": "00000000-0000-0000-0000-000000000000", "type": "reference_table"}}
+    And body with value {"data": {"attributes": {"description": "this is a cloud table generated via a cloud bucket sync", "file_metadata": {"access_details": {"aws_detail": {"aws_account_id": "test-account-id", "aws_bucket_name": "test-bucket", "file_path": "test_rt.csv"}}, "sync_enabled": true}, "schema": {"fields": [{"name": "id", "type": "INT32"}, {"name": "name", "type": "STRING"}], "primary_keys": ["id"]}, "sync_enabled": false, "tags": ["test_tag"]}, "type": "reference_table"}}
     When the request is sent
     Then the response status is 400 Bad Request
 
   @generated @skip @team:DataDog/redapl-experiences
   Scenario: Update reference table returns "OK" response
     Given new "UpdateReferenceTable" request
     And request contains "id" parameter from "REPLACE.ME"
-    And body with value {"data": {"attributes": {"description": "this is a cloud table generated via a cloud bucket sync", "file_metadata": {"access_details": {"aws_detail": {"aws_account_id": "test-account-id", "aws_bucket_name": "test-bucket", "file_path": "test_rt.csv"}}, "sync_enabled": true}, "schema": {"fields": [{"name": "id", "type": "INT32"}, {"name": "name", "type": "STRING"}], "primary_keys": ["id"]}, "sync_enabled": false, "tags": ["test_tag"]}, "id": "00000000-0000-0000-0000-000000000000", "type": "reference_table"}}
+    And body with value {"data": {"attributes": {"description": "this is a cloud table generated via a cloud bucket sync", "file_metadata": {"access_details": {"aws_detail": {"aws_account_id": "test-account-id", "aws_bucket_name": "test-bucket", "file_path": "test_rt.csv"}}, "sync_enabled": true}, "schema": {"fields": [{"name": "id", "type": "INT32"}, {"name": "name", "type": "STRING"}], "primary_keys": ["id"]}, "sync_enabled": false, "tags": ["test_tag"]}, "type": "reference_table"}}
     When the request is sent
     Then the response status is 200 OK

services/reference_tables/src/v2/ReferenceTablesApi.ts

@@ -847,15 +847,15 @@ export interface ReferenceTablesApiCreateReferenceTableUploadRequest {
 
 export interface ReferenceTablesApiDeleteTableRequest {
   /**
-   * The ID of the reference table to delete
+   * Unique identifier of the reference table to delete
    * @type string
    */
   id: string;
 }
 
 export interface ReferenceTablesApiGetRowsByIDRequest {
   /**
-   * The ID of the reference table
+   * Unique identifier of the reference table to get rows from
    * @type string
    */
   id: string;
@@ -868,7 +868,7 @@ export interface ReferenceTablesApiGetRowsByIDRequest {
 
 export interface ReferenceTablesApiGetTableRequest {
   /**
-   * The ID of the reference table to retrieve
+   * Unique identifier of the reference table to retrieve
    * @type string
    */
   id: string;
@@ -886,7 +886,7 @@ export interface ReferenceTablesApiListTablesRequest {
    */
   pageOffset?: number;
   /**
-   * Sort field and direction. Use field name for ascending, prefix with "-" for descending.
+   * Sort field and direction for the list of reference tables. Use field name for ascending, prefix with "-" for descending.
    * @type ReferenceTableSortType
    */
   sort?: ReferenceTableSortType;
@@ -909,7 +909,7 @@ export interface ReferenceTablesApiListTablesRequest {
 
 export interface ReferenceTablesApiUpdateReferenceTableRequest {
   /**
-   * The ID of the reference table to update
+   * Unique identifier of the reference table to update
    * @type string
    */
   id: string;
@@ -940,7 +940,11 @@ export class ReferenceTablesApi {
   }
 
   /**
-   * Create a new reference table. You can provide data in two ways: 1) Call POST api/v2/reference-tables/upload first to get an upload ID, then PUT chunks of CSV data to each provided URL, and finally call this POST endpoint with the upload_id in file_metadata, OR 2) Provide access_details in file_metadata pointing to a CSV file in cloud storage (Amazon S3, Azure Blob Storage, or GCP Cloud Storage).
+   * Creates a reference table. You can provide data in two ways:
+   * 1. Call POST /api/v2/reference-tables/upload to get an upload ID. Then, PUT the CSV data
+   *    (not the file itself) in chunks to each URL in the request body. Finally, call this
+   *    POST endpoint with `upload_id` in `file_metadata`.
+   * 2. Provide `access_details` in `file_metadata` pointing to a CSV file in cloud storage.
    * @param param The request object
    */
   public createReferenceTable(

services/reference_tables/src/v2/models/CreateTableRequest.ts

@@ -3,11 +3,11 @@ import { AttributeTypeMap } from "@datadog/datadog-api-client";
 import { CreateTableRequestData } from "./CreateTableRequestData";
 
 /**
- * The definition of `CreateTableRequest` object.
+ * Request body for creating a new reference table from a local file or cloud storage.
  */
 export class CreateTableRequest {
   /**
-   * The definition of `CreateTableRequestData` object.
+   * The data object containing the table definition.
    */
   "data"?: CreateTableRequestData;
   /**

services/reference_tables/src/v2/models/CreateTableRequestData.ts

@@ -4,27 +4,17 @@ import { CreateTableRequestDataAttributes } from "./CreateTableRequestDataAttrib
 import { CreateTableRequestDataType } from "./CreateTableRequestDataType";
 
 /**
- * The definition of `CreateTableRequestData` object.
+ * The data object containing the table definition.
  */
 export class CreateTableRequestData {
   /**
-   * The definition of `CreateTableRequestDataAttributes` object.
+   * Attributes that define the reference table's configuration and properties.
    */
   "attributes"?: CreateTableRequestDataAttributes;
-  /**
-   * The ID of the reference table.
-   */
-  "id"?: string;
   /**
    * Reference table resource type.
    */
   "type": CreateTableRequestDataType;
-  /**
-   * A container for additional, undeclared properties.
-   * This is a holder for any undeclared properties as specified with
-   * the 'additionalProperties' keyword in the OAS document.
-   */
-  "additionalProperties"?: { [key: string]: any };
   /**
    * @ignore
    */
@@ -38,19 +28,11 @@ export class CreateTableRequestData {
       baseName: "attributes",
       type: "CreateTableRequestDataAttributes",
     },
-    id: {
-      baseName: "id",
-      type: "string",
-    },
     type: {
       baseName: "type",
       type: "CreateTableRequestDataType",
       required: true,
     },
-    additionalProperties: {
-      baseName: "additionalProperties",
-      type: "{ [key: string]: any; }",
-    },
   };
 
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributes.ts

@@ -5,31 +5,31 @@ import { CreateTableRequestDataAttributesSchema } from "./CreateTableRequestData
 import { ReferenceTableCreateSourceType } from "./ReferenceTableCreateSourceType";
 
 /**
- * The definition of `CreateTableRequestDataAttributes` object.
+ * Attributes that define the reference table's configuration and properties.
  */
 export class CreateTableRequestDataAttributes {
   /**
-   * The description of the reference table.
+   * Optional text describing the purpose or contents of this reference table.
    */
   "description"?: string;
   /**
-   * The definition of `CreateTableRequestDataAttributesFileMetadata` object.
+   * Metadata specifying where and how to access the reference table's data file.
    */
   "fileMetadata"?: CreateTableRequestDataAttributesFileMetadata;
   /**
-   * The definition of `CreateTableRequestDataAttributesSchema` object.
+   * Schema defining the structure and columns of the reference table.
    */
   "schema": CreateTableRequestDataAttributesSchema;
   /**
    * The source type for creating reference table data. Only these source types can be created through this API.
    */
   "source": ReferenceTableCreateSourceType;
   /**
-   * The name of the reference table.
+   * Name to identify this reference table.
    */
   "tableName": string;
   /**
-   * The tags of the reference table.
+   * Tags for organizing and filtering reference tables.
    */
   "tags"?: Array<string>;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadata.ts

@@ -4,7 +4,7 @@ import { CreateTableRequestDataAttributesFileMetadataCloudStorage } from "./Crea
 import { CreateTableRequestDataAttributesFileMetadataLocalFile } from "./CreateTableRequestDataAttributesFileMetadataLocalFile";
 
 /**
- * The definition of `CreateTableRequestDataAttributesFileMetadata` object.
+ * Metadata specifying where and how to access the reference table's data file.
  */
 export type CreateTableRequestDataAttributesFileMetadata =
   | CreateTableRequestDataAttributesFileMetadataCloudStorage

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadataCloudStorage.ts

@@ -7,7 +7,7 @@ import { CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails } from "
  */
 export class CreateTableRequestDataAttributesFileMetadataCloudStorage {
   /**
-   * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails` object.
+   * Cloud storage access configuration for the reference table data file.
    */
   "accessDetails": CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails.ts

@@ -5,19 +5,19 @@ import { CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDeta
 import { CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail } from "./CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail";
 
 /**
- * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails` object.
+ * Cloud storage access configuration for the reference table data file.
  */
 export class CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails {
   /**
-   * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail` object.
+   * Amazon Web Services S3 storage access configuration.
    */
   "awsDetail"?: CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail;
   /**
-   * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail` object.
+   * Azure Blob Storage access configuration.
    */
   "azureDetail"?: CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail;
   /**
-   * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail` object.
+   * Google Cloud Platform storage access configuration.
    */
   "gcpDetail"?: CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail.ts

@@ -1,15 +1,15 @@
 import { AttributeTypeMap } from "@datadog/datadog-api-client";
 
 /**
- * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail` object.
+ * Amazon Web Services S3 storage access configuration.
  */
 export class CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail {
   /**
-   * The ID of the AWS account.
+   * AWS account ID where the S3 bucket is located.
    */
   "awsAccountId": string;
   /**
-   * The name of the Amazon S3 bucket.
+   * S3 bucket containing the CSV file.
    */
   "awsBucketName": string;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail.ts

@@ -1,23 +1,23 @@
 import { AttributeTypeMap } from "@datadog/datadog-api-client";
 
 /**
- * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail` object.
+ * Azure Blob Storage access configuration.
  */
 export class CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail {
   /**
-   * The Azure client ID.
+   * Azure service principal (application) client ID with permissions to read from the container.
    */
   "azureClientId": string;
   /**
-   * The name of the Azure container.
+   * Azure Blob Storage container containing the CSV file.
    */
   "azureContainerName": string;
   /**
-   * The name of the Azure storage account.
+   * Azure storage account where the container is located.
    */
   "azureStorageAccountName": string;
   /**
-   * The ID of the Azure tenant.
+   * Azure Active Directory tenant ID.
    */
   "azureTenantId": string;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail.ts

@@ -1,23 +1,23 @@
 import { AttributeTypeMap } from "@datadog/datadog-api-client";
 
 /**
- * The definition of `CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail` object.
+ * Google Cloud Platform storage access configuration.
  */
 export class CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail {
   /**
    * The relative file path from the GCS bucket root to the CSV file.
    */
   "filePath": string;
   /**
-   * The name of the GCP bucket.
+   * GCP bucket containing the CSV file.
    */
   "gcpBucketName": string;
   /**
-   * The ID of the GCP project.
+   * GCP project ID where the bucket is located.
    */
   "gcpProjectId": string;
   /**
-   * The email of the GCP service account.
+   * Service account email with read permissions for the GCS bucket.
    */
   "gcpServiceAccountEmail": string;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesSchema.ts

@@ -3,11 +3,11 @@ import { AttributeTypeMap } from "@datadog/datadog-api-client";
 import { CreateTableRequestDataAttributesSchemaFieldsItems } from "./CreateTableRequestDataAttributesSchemaFieldsItems";
 
 /**
- * The definition of `CreateTableRequestDataAttributesSchema` object.
+ * Schema defining the structure and columns of the reference table.
  */
 export class CreateTableRequestDataAttributesSchema {
   /**
-   * The `schema` `fields`.
+   * The schema fields.
    */
   "fields": Array<CreateTableRequestDataAttributesSchemaFieldsItems>;
   /**

services/reference_tables/src/v2/models/CreateTableRequestDataAttributesSchemaFieldsItems.ts

@@ -3,7 +3,7 @@ import { AttributeTypeMap } from "@datadog/datadog-api-client";
 import { ReferenceTableSchemaFieldType } from "./ReferenceTableSchemaFieldType";
 
 /**
- * The definition of `CreateTableRequestDataAttributesSchemaFieldsItems` object.
+ * A single field (column) in the reference table schema to be created.
  */
 export class CreateTableRequestDataAttributesSchemaFieldsItems {
   /**

services/reference_tables/src/v2/models/CreateUploadRequest.ts

@@ -3,11 +3,11 @@ import { AttributeTypeMap } from "@datadog/datadog-api-client";
 import { CreateUploadRequestData } from "./CreateUploadRequestData";
 
 /**
- * The definition of `CreateUploadRequest` object.
+ * Request to create an upload for a file to be ingested into a reference table.
  */
 export class CreateUploadRequest {
   /**
-   * The definition of `CreateUploadRequestData` object.
+   * Request data for creating an upload for a file to be ingested into a reference table.
    */
   "data"?: CreateUploadRequestData;
   /**

services/reference_tables/src/v2/models/CreateUploadRequestData.ts

@@ -4,27 +4,17 @@ import { CreateUploadRequestDataAttributes } from "./CreateUploadRequestDataAttr
 import { CreateUploadRequestDataType } from "./CreateUploadRequestDataType";
 
 /**
- * The definition of `CreateUploadRequestData` object.
+ * Request data for creating an upload for a file to be ingested into a reference table.
  */
 export class CreateUploadRequestData {
   /**
-   * The definition of `CreateUploadRequestDataAttributes` object.
+   * Upload configuration specifying how data is uploaded by the user, and properties of the table to associate the upload with.
    */
   "attributes"?: CreateUploadRequestDataAttributes;
-  /**
-   * The ID of the upload.
-   */
-  "id"?: string;
   /**
    * Upload resource type.
    */
   "type": CreateUploadRequestDataType;
-  /**
-   * A container for additional, undeclared properties.
-   * This is a holder for any undeclared properties as specified with
-   * the 'additionalProperties' keyword in the OAS document.
-   */
-  "additionalProperties"?: { [key: string]: any };
   /**
    * @ignore
    */
@@ -38,19 +28,11 @@ export class CreateUploadRequestData {
       baseName: "attributes",
       type: "CreateUploadRequestDataAttributes",
     },
-    id: {
-      baseName: "id",
-      type: "string",
-    },
     type: {
       baseName: "type",
       type: "CreateUploadRequestDataType",
       required: true,
     },
-    additionalProperties: {
-      baseName: "additionalProperties",
-      type: "{ [key: string]: any; }",
-    },
   };
 
   /**