Repository navigation
feat(specs): add analytics v3 pattern endpoints - #6795
Conversation
βοΈ Code generated!
π Benchmark resultsBenchmarks performed on the method using a mock server, the results might not reflect the real-world performance.
|
| description: | | ||
| **Beta**: this endpoint is under active development and may change without notice. | ||
|
|
||
| Aggregates the requested `metrics` over the whole period and returns a single object keyed by metric | ||
| kind. `metrics` and `parameters` are required; `filters` is optional. Discover valid field kinds per | ||
| domain with `/3/patterns/fields`. | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../common/schemas/patterns.yml#/ScalarPayload' |
There was a problem hiding this comment.
Looks good to me overall, and I donβt think this needs to block the PR. One thing to note:
- These generated methods receive the indices through the request body.
- The current Analytics backend performs index authorization earlier, using the
indexURL query parameter. - Unrestricted API keys work without that URL parameter.
- With an index-restricted key, the consumer currently also needs to provide
?index=indexA,indexBthrough the generic request options. - For scalar, table, and timeseries, the backend then verifies that the URL and body indices match.
The generated client shape here looks reasonable, but restricted-key callers still have this non-obvious backend constraint.
There was a problem hiding this comment.
Updated the code to add the indices in the query param too (but not required)
| parameters: | ||
| - in: header | ||
| name: If-None-Match | ||
| required: false | ||
| description: Prior `ETag`. Returns `304 Not Modified` when the catalog is unchanged. | ||
| schema: | ||
| type: string | ||
| responses: | ||
| '200': | ||
| description: OK | ||
| headers: | ||
| x-ratelimit-limit: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-limit' | ||
| x-ratelimit-remaining: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-remaining' | ||
| x-ratelimit-reset: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-reset' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../common/schemas/patterns.yml#/Catalog' | ||
| '304': | ||
| description: Not Modified β the catalog matches the supplied `If-None-Match`. |
There was a problem hiding this comment.
I was looking into the caching behavior here because If-None-Match and 304 are different from how the other Analytics endpoints work. I think there may be a gap between what this method exposes and what the generated clients currently support:
- The four query endpoints use backend Redis caching. Consumers always receive
200and do not manage caching themselves. - This endpointβs ETag flow requires the consumer to retrieve the ETag, store both the ETag and catalog, explicitly pass
ifNoneMatchlater, and reuse the stored catalog after a304. - The generated client does not manage those steps automatically.
- The generated JavaScript client does send
If-None-Matchwhen requested, but its transporter only treats2xxresponses as successful. It classifies a valid304as retryable and eventually throws, including from the HTTP-info method.
Given that the manual ETag flow is not currently supported end to end, would it be better to avoid exposing If-None-Match and 304 in the generated method for now?
| TimeseriesResponse: | ||
| type: object | ||
| title: Timeseries response | ||
| additionalProperties: false | ||
| properties: | ||
| series: | ||
| type: array | ||
| description: One entry per `groupBy` combination. | ||
| items: | ||
| title: series | ||
| type: object | ||
| additionalProperties: false | ||
| properties: | ||
| key: | ||
| type: object | ||
| description: The `groupBy` values identifying this series. Absent when the query has no `groupBy`. | ||
| additionalProperties: true | ||
| totals: | ||
| type: object | ||
| description: Metric totals over the whole period. | ||
| additionalProperties: true | ||
| dates: | ||
| type: array | ||
| description: Per-day metric breakdown. | ||
| items: | ||
| title: seriesDate | ||
| type: object | ||
| additionalProperties: false | ||
| properties: | ||
| date: | ||
| type: string | ||
| description: Day, formatted as YYYY-MM-DD. | ||
| metrics: | ||
| type: object | ||
| description: Metric values for the day. | ||
| additionalProperties: true | ||
|
|
||
| TableResponse: | ||
| type: object | ||
| title: Table response | ||
| additionalProperties: false | ||
| properties: | ||
| rows: | ||
| type: array | ||
| description: Result rows. Each row is a flat object of the requested fields. | ||
| items: | ||
| type: object | ||
| additionalProperties: true | ||
|
|
||
| ScalarResponse: | ||
| type: object | ||
| title: Scalar response | ||
| description: Object keyed by metric kind, each mapping to its aggregate value. | ||
| additionalProperties: true | ||
|
|
||
| DistributionResponse: | ||
| type: object | ||
| title: Distribution response | ||
| description: Object keyed by `histogram<Field>`, each mapping a bin label to a count. | ||
| additionalProperties: true | ||
|
|
||
| Catalog: | ||
| type: object | ||
| title: Field catalog | ||
| additionalProperties: false | ||
| properties: | ||
| domains: | ||
| type: object | ||
| description: Catalog entries grouped by domain. | ||
| additionalProperties: | ||
| $ref: '#/DomainCatalog' | ||
|
|
||
| DomainCatalog: | ||
| type: object | ||
| title: Domain catalog | ||
| additionalProperties: false | ||
| properties: | ||
| metrics: | ||
| type: array | ||
| description: Fields usable as metrics. | ||
| items: | ||
| $ref: '#/CatalogEntry' | ||
| filters: | ||
| type: array | ||
| description: Fields usable as filters. | ||
| items: | ||
| $ref: '#/CatalogEntry' | ||
| groups: | ||
| type: array | ||
| description: Fields usable in `groupBy`. | ||
| items: | ||
| $ref: '#/CatalogEntry' | ||
| distributions: | ||
| type: array | ||
| description: Fields usable in distributions. | ||
| items: | ||
| $ref: '#/CatalogEntry' | ||
|
|
||
| CatalogEntry: | ||
| type: object | ||
| title: Catalog entry | ||
| additionalProperties: false | ||
| required: | ||
| - kind | ||
| properties: | ||
| kind: | ||
| type: string | ||
| description: Field identifier. | ||
| description: | ||
| type: string | ||
| description: Human-readable description of the field. | ||
| roots: | ||
| type: array | ||
| description: Root stages the field depends on. Two fields are combinable in one query only when their roots intersect. | ||
| items: | ||
| type: string | ||
| requires: | ||
| type: array | ||
| description: Public ACL identifiers required to read the field, for example `clickAnalyticsEnabled`. | ||
| items: | ||
| type: string |
There was a problem hiding this comment.
I noticed that the requiredness of these response models does not currently match what the Analytics backend serializes:
- The backend always includes
series,totals,dates,date,metrics,rows,domains, and the catalog arrays because those Go fields do not useomitempty. keyis the exception and is genuinely optional.- The current schemas do not mark the other fields as required, so generated clients model them as optional. For example, JavaScript generates
rows?: ...andseries?: ..., even though the backend does not omit those properties. - There is also a nullability difference for an empty timeseries. The backend currently leaves
seriesas a nil slice and serializes"series": null, while this schema describes an optional, non-null array.
Could we align the response contract before publishing these models, including deciding whether an empty timeseries should return [] or null and marking the fields that are always present as required?
There was a problem hiding this comment.
I updated to add the required to the field responses + made timeseries response nullable (I prefer matching the contract to the go code for now)
| get: | ||
| tags: | ||
| - pattern | ||
| operationId: getPatternsFields | ||
| x-acl: | ||
| - analytics | ||
| summary: (Beta) Retrieve the field catalog | ||
| description: | | ||
| **Beta**: this endpoint is under active development and may change without notice. | ||
|
|
||
| Returns the catalog of analytics fields available to the caller, grouped by domain and usage | ||
| (metrics, filters, groups, distributions). Use it to discover valid `(domain, kind)` pairs before | ||
| building the other `/3/patterns/*` queries. Two fields are combinable in one query only when their | ||
| `roots` intersect. | ||
| parameters: | ||
| - in: header | ||
| name: If-None-Match | ||
| required: false | ||
| description: Prior `ETag`. Returns `304 Not Modified` when the catalog is unchanged. | ||
| schema: | ||
| type: string | ||
| responses: | ||
| '200': | ||
| description: OK | ||
| headers: | ||
| x-ratelimit-limit: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-limit' | ||
| x-ratelimit-remaining: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-remaining' | ||
| x-ratelimit-reset: | ||
| $ref: '../../../common/responses/rateLimit.yml#/x-ratelimit-reset' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '../../common/schemas/patterns.yml#/Catalog' | ||
| '304': | ||
| description: Not Modified β the catalog matches the supplied `If-None-Match`. | ||
| '400': | ||
| $ref: '../../../common/responses/BadRequest.yml' | ||
| '402': | ||
| $ref: '../../../common/responses/FeatureNotEnabled.yml' | ||
| '403': | ||
| $ref: '../../../common/responses/MethodNotAllowed.yml' |
There was a problem hiding this comment.
I noticed a difference between the contract described here and how the current Analytics backend registers this endpoint:
- The backend registers
/3/patterns/fieldswithout the normal authentication or rate-limit middleware. It requires no application ID, API key, or Analytics ACL. - The handler returns the complete static catalog. Each catalog entryβs
requiresfield explains the permissions needed when that field is later used in a query. - This specification inherits the Analytics APIβs global application ID and API-key security and declares
x-acl: analytics. The generated JavaScript documentation consequently says that theanalyticsACL is required. - The response here declares the normal Analytics rate-limit headers, while the backend instead emits
ETagandCache-Controlfor this route.
Authenticated consumers can still call the endpoint because the additional credentials are harmless. The difference is that the backend presents it as an anonymous, cache-oriented discovery endpoint, while the generated contract presents it as an authenticated, rate-limited Analytics operation.
There was a problem hiding this comment.
I removed the auth check for this route
Summary by Aikido
β‘ Enhancements
|
β¦skip ci] Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
algolia/api-clients-automation#6795 Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com> Co-authored-by: My Lan Aragon <mylan.aragon@algolia.com>
π§ What and Why
Adds the semantic-patterns framework (
/3/patterns/*) endpoints to the existing analytics client spec so it gets public clients generated. It's additive, no changes to/2/*.Since these endpoints aren't fully stable yet, they're tagged beta (via the Patterns (Beta) tag + (Beta) summaries). They live in the existing analytics client rather than a dedicated v3 one, since they're additive.
Changes included:
specs/analytics/common/schemas/patterns.yml: payload/response/catalog schemas (+limit/offset)specs/analytics/paths/patterns/:getPatternsFields(GET) +queryPatterns{Timeseries,Scalar,Table,Distribution}(POST)specs/analytics/spec.yml: wire the 5 paths, addpatterntag + group, note in version proseπ§ͺ Test