Validate ml.get_* API (#394)

Author: philkra

output/schema/schema.json

@@ -564,18 +564,6 @@
       ],
       "response": []
     },
-    "ml.get_calendars": {
-      "request": [
-        "Endpoint has \"@stability: TODO"
-      ],
-      "response": []
-    },
-    "ml.get_categories": {
-      "request": [
-        "Endpoint has \"@stability: TODO"
-      ],
-      "response": []
-    },
     "ml.get_datafeed_stats": {
       "request": [
         "Endpoint has \"@stability: TODO"
@@ -588,12 +576,6 @@
       ],
       "response": []
     },
-    "ml.get_influencers": {
-      "request": [
-        "Endpoint has \"@stability: TODO"
-      ],
-      "response": []
-    },
     "ml.get_job_stats": {
       "request": [
         "Endpoint has \"@stability: TODO"

output/schema/validation-errors.json

@@ -9918,24 +9918,33 @@ export type MlAppliesTo = 'actual' | 'typical' | 'diff_from_typical' | 'time'
 
 export interface MlBucketInfluencer {
   bucket_span: long
-  influencer_field_name: string
-  influencer_field_value: string
   influencer_score: double
+  influencer_field_name: Field
+  influencer_field_value: string
   initial_influencer_score: double
   is_interim: boolean
   job_id: Id
   probability: double
   result_type: string
-  timestamp: DateString
+  timestamp: Time
+  foo?: string
 }
 
 export interface MlCategoryDefinition {
-  category_id: long
+  category_id: ulong
   examples: string[]
+  grok_pattern?: string
   job_id: Id
-  max_matching_length: long
+  max_matching_length: ulong
+  partition_field_name?: string
+  partition_field_value?: string
   regex: string
   terms: string
+  num_matches?: long
+  preferred_to_categories?: Id[]
+  p?: string
+  result_type: string
+  mlcategory: string
 }
 
 export interface MlChunkingConfig {
@@ -10333,8 +10342,8 @@ export interface MlOverallBucketJobInfo {
 }
 
 export interface MlPage {
-  from: integer
-  size: integer
+  from?: integer
+  size?: integer
 }
 
 export interface MlPartitionScore {
@@ -10776,12 +10785,14 @@ export interface MlGetCalendarEventsResponse {
 
 export interface MlGetCalendarsCalendar {
   calendar_id: Id
-  description: string
+  description?: string
   job_ids: Id[]
 }
 
 export interface MlGetCalendarsRequest extends RequestBase {
   calendar_id?: Id
+  from?: integer
+  size?: integer
   body?: {
     page?: MlPage
   }
@@ -10795,6 +10806,9 @@ export interface MlGetCalendarsResponse {
 export interface MlGetCategoriesRequest extends RequestBase {
   job_id: Id
   category_id?: CategoryId
+  from?: integer
+  size?: integer
+  partition_field_value?: string
   body?: {
     page?: MlPage
   }
@@ -10970,14 +10984,16 @@ export interface MlGetFiltersResponse {
 
 export interface MlGetInfluencersRequest extends RequestBase {
   job_id: Id
+  desc?: boolean
+  end?: DateString
+  exclude_interim?: boolean
+  influencer_score?: double
+  from?: integer
+  size?: integer
+  sort?: Field
+  start?: DateString
   body?: {
-    descending?: boolean
-    end?: DateString
-    exclude_interim?: boolean
-    influencer_score?: double
     page?: MlPage
-    sort?: Field
-    start?: DateString
   }
 }
 

output/typescript/types.ts

@@ -17,19 +17,30 @@
  * under the License.
  */
 
-import { Id } from '@_types/common'
+import { Field, Id } from '@_types/common'
 import { double, long } from '@_types/Numeric'
-import { DateString } from '@_types/Time'
+import { Time } from '@_types/Time'
 
 export class BucketInfluencer {
+  /** The length of the bucket in seconds. This value matches the bucket_span that is specified in the job. */
   bucket_span: long
-  influencer_field_name: string
-  influencer_field_value: string
+  /** A normalized score between 0-100, which is based on the probability of the influencer in this bucket aggregated across detectors. Unlike initial_influencer_score, this value will be updated by a re-normalization process as new data is analyzed. */
   influencer_score: double
+  /** The field name of the influencer. */
+  influencer_field_name: Field
+  /** The entity that influenced, contributed to, or was to blame for the anomaly. */
+  influencer_field_value: string
+  /** A normalized score between 0-100, which is based on the probability of the influencer aggregated across detectors. This is the initial value that was calculated at the time the bucket was processed. */
   initial_influencer_score: double
+  /** If true, this is an interim result. In other words, the results are calculated based on partial input data. */
   is_interim: boolean
+  /** Identifier for the anomaly detection job. */
   job_id: Id
+  /** The probability that the influencer has this behavior, in the range 0 to 1. This value can be held to a high precision of over 300 decimal places, so the influencer_score is provided as a human-readable and friendly interpretation of this. */
   probability: double
+  /** Internal. This value is always set to influencer. */
   result_type: string
-  timestamp: DateString
+  /** The start time of the bucket for which these results were calculated. */
+  timestamp: Time
+  foo?: string // TODO ??? - the tests carry this prop but :shrug:
 }

specification/ml/_types/BucketInfluencer.ts

@@ -18,13 +18,32 @@
  */
 
 import { Id } from '@_types/common'
-import { long } from '@_types/Numeric'
+import { long, ulong } from '@_types/Numeric'
 
 export class CategoryDefinition {
-  category_id: long
+  /** A unique identifier for the category. category_id is unique at the job level, even when per-partition categorization is enabled. */
+  category_id: ulong
+  /** A list of examples of actual values that matched the category. */
   examples: string[]
+  /** [experimental] A Grok pattern that could be used in Logstash or an ingest pipeline to extract fields from messages that match the category. This field is experimental and may be changed or removed in a future release. The Grok patterns that are found are not optimal, but are often a good starting point for manual tweaking. */
+  grok_pattern?: string
+  /** Identifier for the anomaly detection job. */
   job_id: Id
-  max_matching_length: long
+  /** The maximum length of the fields that matched the category. The value is increased by 10% to enable matching for similar fields that have not been analyzed. */
+  max_matching_length: ulong
+  /** If per-partition categorization is enabled, this property identifies the field used to segment the categorization. It is not present when per-partition categorization is disabled. */
+  partition_field_name?: string
+  /** If per-partition categorization is enabled, this property identifies the value of the partition_field_name for the category. It is not present when per-partition categorization is disabled. */
+  partition_field_value?: string
+  /** A regular expression that is used to search for values that match the category. */
   regex: string
+  /** A space separated list of the common tokens that are matched in values of the category. */
   terms: string
+  /** The number of messages that have been matched by this category. This is only guaranteed to have the latest accurate count after a job _flush or _close */
+  num_matches?: long
+  /** A list of category_id entries that this current category encompasses. Any new message that is processed by the categorizer will match against this category and not any of the categories in this list. This is only guaranteed to have the latest accurate list of categories after a job _flush or _close */
+  preferred_to_categories?: Id[]
+  p?: string
+  result_type: string
+  mlcategory: string
 }

specification/ml/_types/CategoryDefinition.ts

@@ -20,6 +20,6 @@
 import { integer } from '@_types/Numeric'
 
 export class Page {
-  from: integer
-  size: integer
+  from?: integer
+  size?: integer
 }

specification/ml/_types/Page.ts

@@ -20,7 +20,9 @@
 import { Id } from '@_types/common'
 
 export class Calendar {
+  /** A string that uniquely identifies a calendar. */
   calendar_id: Id
-  description: string
+  description?: string
+  /** An array of anomaly detection job identifiers.  */
   job_ids: Id[]
 }

specification/ml/get_calendars/Calendar.ts

@@ -20,6 +20,7 @@
 import { Page } from '@ml/_types/Page'
 import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
+import { integer } from '@_types/Numeric'
 
 /**
  * @rest_spec_name ml.get_calendars
@@ -28,9 +29,15 @@ import { Id } from '@_types/common'
  */
 export interface Request extends RequestBase {
   path_parts?: {
+    /** A string that uniquely identifies a calendar. */
     calendar_id?: Id
   }
-  query_parameters?: {}
+  query_parameters?: {
+    /** Skips the specified number of calendars. */
+    from?: integer
+    /** Specifies the maximum number of calendars to obtain. */
+    size?: integer
+  }
   body?: {
     page?: Page
   }

specification/ml/get_calendars/MlGetCalendarsRequest.ts

@@ -20,6 +20,7 @@
 import { Page } from '@ml/_types/Page'
 import { RequestBase } from '@_types/Base'
 import { CategoryId, Id } from '@_types/common'
+import { integer } from '@_types/Numeric'
 
 /**
  * @rest_spec_name ml.get_categories
@@ -28,9 +29,17 @@ import { CategoryId, Id } from '@_types/common'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /** Identifier for the anomaly detection job. */
     job_id: Id
+    /** Identifier for the category, which is unique in the job. If you specify neither the category ID nor the partition_field_value, the API returns information about all categories. If you specify only the partition_field_value, it returns information about all categories for the specified partition. */
     category_id?: CategoryId
   }
+  query_parameters?: {
+    from?: integer
+    size?: integer
+    /** Only return categories for the specified partition. */
+    partition_field_value?: string
+  }
   body?: {
     page?: Page
   }

specification/ml/get_categories/MlGetCategoriesRequest.ts

@@ -20,7 +20,7 @@
 import { Page } from '@ml/_types/Page'
 import { RequestBase } from '@_types/Base'
 import { Field, Id } from '@_types/common'
-import { double } from '@_types/Numeric'
+import { double, integer } from '@_types/Numeric'
 import { DateString } from '@_types/Time'
 
 /**
@@ -30,16 +30,31 @@ import { DateString } from '@_types/Time'
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /** Identifier for the anomaly detection job. */
     job_id: Id
   }
-  query_parameters?: {}
-  body?: {
-    descending?: boolean
+  query_parameters?: {
+    /**
+     * If true, the results are sorted in descending order.
+     * @server_default false
+     */
+    desc?: boolean
+    /** Returns influencers with timestamps earlier than this time. */
     end?: DateString
+    /** If true, the output excludes interim results. By default, interim results are included. */
     exclude_interim?: boolean
+    /** Returns influencers with anomaly scores greater than or equal to this value. */
     influencer_score?: double
-    page?: Page
+    /** Skips the specified number of influencers. */
+    from?: integer
+    /** Specifies the maximum number of influencers to obtain. */
+    size?: integer
+    /** Specifies the sort field for the requested influencers. By default, the influencers are sorted by the influencer_score value. */
     sort?: Field
+    /** Returns influencers with timestamps after this time. */
     start?: DateString
   }
+  body?: {
+    page?: Page
+  }
 }

specification/ml/get_influencers/MlGetInfluencersRequest.ts

@@ -21,5 +21,9 @@ import { BucketInfluencer } from '@ml/_types/BucketInfluencer'
 import { long } from '@_types/Numeric'
 
 export class Response {
-  body: { count: long; influencers: BucketInfluencer[] }
+  body: {
+    count: long
+    /** Array of influencer objects */
+    influencers: BucketInfluencer[]
+  }
 }