Skip to content

Clarify JavaScript source map listing and pagination #4733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dd-octo-sts wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Clarify JavaScript source map listing and pagination #4733

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 151 additions & 10 deletions .generator/schemas/v2/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65561,6 +65561,12 @@ components:
example: "2024-01-01T00:00:00Z"
format: date-time
type: string
debug_id:
description: |-
The debug identifier (UUID format) that uniquely identifies this
JavaScript source map. Returned for source maps indexed by debug ID.
example: 00000000-0000-4000-8000-000000000001
type: string
domain:
description: The domain associated with the source map.
example: example.com
Expand Down Expand Up @@ -120642,6 +120648,14 @@ components:
- ELF
- NDK
- IL2CPP
SourcemapSearchBy:
description: The search mode for listing JavaScript source maps.
enum:
- debug_id
example: debug_id
type: string
x-enum-varnames:
- DEBUG_ID
SourcemapsData:
description: List of source map data objects.
items:
Expand All @@ -120662,8 +120676,17 @@ components:
description: Whether there are more results available beyond the current page.
example: false
type: boolean
next_cursor:
description: |-
Cursor for the next page of a JavaScript cursor-based listing. Pass
this value as `page[after]` with the same search mode and filters.
Only returned when another page is available.
type: string
total_filtered_count:
description: Total number of source maps matching the filter criteria.
description: |-
Total number of matching source maps for legacy page-number pagination.
Cursor-based listings do not compute a total; this field may be zero
even when records are returned. Use `has_more_results` to continue.
example: 100
format: int64
type: integer
Expand Down Expand Up @@ -231257,33 +231280,129 @@ paths:
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
/api/v2/sourcemaps/list:
get:
description: Retrieves a paginated list of source maps matching the specified filter criteria.
description: |-
Retrieves a paginated list of source maps. Send filters as query parameters,
not in a JSON request body. `mapkind` defaults to `js`.

For JavaScript source maps, choose one of these searches:

- **Service and version:** provide both `filter[service]` and `filter[version]`.
This searches source maps indexed by service and version.
- **One debug ID:** provide `filter[debug_id]` with a UUID to look up the single
source map with that debug ID. Service and version are not required for this
JavaScript search.
- **Browse debug IDs:** set `search_by=debug_id` to list source maps indexed by
debug ID without specifying an ID. Do not send service, version, or filename
filters in this mode.

**Pagination:** for JavaScript listings, omit `page[after]` and `page[number]`
to start at the first page. Copy `meta.page.next_cursor` into `page[after]` on
the next request, keeping the same search mode and filters. Continue until
`meta.page.has_more_results` is `false`. Do not decode or modify the cursor.
Debug-ID browsing requires cursor pagination; `page[number]` is not supported.
A specific `filter[debug_id]` lookup without `search_by=debug_id` does not support
`page[after]`. Other map kinds use `page[number]`, starting at 1.

**Examples:** the following commands use the US1 API host. Replace the host with
the API host for your site, and the service, version, debug ID, and cursor with
values from your organization. Use `--get` so curl sends the filters in the query
string; `-X GET` with `--data-urlencode` sends them in the request body instead.

**List by service and version**

```bash
curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
--data-urlencode "mapkind=js" \
--data-urlencode "filter[service]=my-web-service" \
--data-urlencode "filter[version]=1.0.0" \
--data-urlencode "page[size]=10"
```

**Find a specific JavaScript debug ID**

```bash
curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
--data-urlencode "mapkind=js" \
--data-urlencode "filter[debug_id]=00000000-0000-4000-8000-000000000001"
```

**Browse debug-ID source maps from the first page**

```bash
curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
--data-urlencode "mapkind=js" \
--data-urlencode "search_by=debug_id" \
--data-urlencode "page[size]=10"
```

**Get the next page of debug-ID source maps**

```bash
curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
--data-urlencode "mapkind=js" \
--data-urlencode "search_by=debug_id" \
--data-urlencode "page[size]=10" \
--data-urlencode "page[after]=<meta.page.next_cursor>"
```
operationId: ListSourcemaps
parameters:
- description: |-
Set to `debug_id` to browse JavaScript source maps indexed by debug ID.
Only supported for `mapkind=js`. Omit for service/version searches or a
specific `filter[debug_id]` lookup. In debug-ID browse mode, service,
version, and filename filters are not supported.
example: debug_id
in: query
name: search_by
schema:
$ref: "#/components/schemas/SourcemapSearchBy"
x-docs-curl-required: true
- description: The type of source map. Defaults to `js`.
in: query
name: mapkind
schema:
$ref: "#/components/schemas/SourcemapMapKind"
- description: The number of results to return per page. Must be at least 1.
- description: |-
Cursor for the next page of a JavaScript listing. Use the value from
`meta.page.next_cursor` and keep the same search mode and filters.
Omit on the first request. Not supported for other map kinds or for
a specific `filter[debug_id]` lookup without `search_by=debug_id`.
in: query
name: page[after]
schema:
type: string
- description: The number of results per page. Defaults to 100. Must be at least 1; values above 1000 are capped at 1000.
in: query
name: page[size]
schema:
default: 20
example: 20
default: 100
example: 10
format: int64
minimum: 1
type: integer
- description: The page number to retrieve, starting from 1.
- description: |-
Legacy page number, starting from 1. Prefer `page[after]` for JavaScript
listings. Not supported with `search_by=debug_id`. Other map kinds
default to page 1 when pagination parameters are omitted.
in: query
name: page[number]
schema:
default: 1
example: 1
format: int64
minimum: 1
type: integer
- description: |-
Filter by service names (multiple values allowed). Required for
`js`, `jvm`, `react`, and `flutter` map kinds.
`jvm`, `react`, and `flutter` map kinds. Also required for `js` unless
searching by `filter[debug_id]` or browsing with `search_by=debug_id`.
explode: true
in: query
name: filter[service]
Expand All @@ -231296,7 +231415,8 @@ paths:
style: form
- description: |-
Filter by version values (multiple values allowed). Required for
`js`, `jvm`, `react`, and `flutter` map kinds.
`jvm`, `react`, and `flutter` map kinds. Also required for `js` unless
searching by `filter[debug_id]` or browsing with `search_by=debug_id`.
explode: true
in: query
name: filter[version]
Expand Down Expand Up @@ -231413,10 +231533,15 @@ paths:
name: filter[filename]
schema:
type: string
- description: Filter by debug ID (single value). Supported for `react`.
- description: |-
Filter by a single debug ID in UUID format. Supported for `js` and `react`.
For `js`, a debug ID identifies exactly one source map, so the lookup returns
at most one result and does not require service/version filters. For `react`,
a debug ID can match multiple files, and service/version filters remain required.
in: query
name: filter[debug_id]
schema:
format: uuid
type: string
- description: Filter by GNU build ID (single value). Supported for `elf`.
in: query
Expand All @@ -231438,6 +231563,22 @@ paths:
content:
application/json:
examples:
debug_id_listing:
summary: Browse JavaScript source maps by debug ID
value:
data:
- attributes:
created_at: "2024-01-01T00:00:00Z"
debug_id: 00000000-0000-4000-8000-000000000001
mapkind: js
size: 1024
id: "7"
type: sourcemaps
meta:
page:
has_more_results: true
next_cursor: opaque-debug-id-cursor
total_filtered_count: 0
default:
value:
data:
Expand Down
105 changes: 102 additions & 3 deletions api/datadogV2/api_rum.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import (
"time"

"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
"github.com/google/uuid"
)

// RUMApi service type
Expand Down Expand Up @@ -1220,7 +1221,9 @@ func (a *RUMApi) ListRUMEventsWithPagination(ctx _context.Context, o ...ListRUME

// ListSourcemapsOptionalParameters holds optional parameters for ListSourcemaps.
type ListSourcemapsOptionalParameters struct {
SearchBy *SourcemapSearchBy
Mapkind *SourcemapMapKind
PageAfter *string
PageSize *int64
PageNumber *int64
FilterService *[]string
Expand All @@ -1237,7 +1240,7 @@ type ListSourcemapsOptionalParameters struct {
FilterOrigin *[]string
FilterOriginVersion *[]string
FilterFilename *string
FilterDebugId *string
FilterDebugId *uuid.UUID
FilterGnuBuildId *string
FilterGoBuildId *string
FilterFileHash *string
Expand All @@ -1249,12 +1252,24 @@ func NewListSourcemapsOptionalParameters() *ListSourcemapsOptionalParameters {
return &this
}

// WithSearchBy sets the corresponding parameter name and returns the struct.
func (r *ListSourcemapsOptionalParameters) WithSearchBy(searchBy SourcemapSearchBy) *ListSourcemapsOptionalParameters {
r.SearchBy = &searchBy
return r
}

// WithMapkind sets the corresponding parameter name and returns the struct.
func (r *ListSourcemapsOptionalParameters) WithMapkind(mapkind SourcemapMapKind) *ListSourcemapsOptionalParameters {
r.Mapkind = &mapkind
return r
}

// WithPageAfter sets the corresponding parameter name and returns the struct.
func (r *ListSourcemapsOptionalParameters) WithPageAfter(pageAfter string) *ListSourcemapsOptionalParameters {
r.PageAfter = &pageAfter
return r
}

// WithPageSize sets the corresponding parameter name and returns the struct.
func (r *ListSourcemapsOptionalParameters) WithPageSize(pageSize int64) *ListSourcemapsOptionalParameters {
r.PageSize = &pageSize
Expand Down Expand Up @@ -1352,7 +1367,7 @@ func (r *ListSourcemapsOptionalParameters) WithFilterFilename(filterFilename str
}

// WithFilterDebugId sets the corresponding parameter name and returns the struct.
func (r *ListSourcemapsOptionalParameters) WithFilterDebugId(filterDebugId string) *ListSourcemapsOptionalParameters {
func (r *ListSourcemapsOptionalParameters) WithFilterDebugId(filterDebugId uuid.UUID) *ListSourcemapsOptionalParameters {
r.FilterDebugId = &filterDebugId
return r
}
Expand All @@ -1376,7 +1391,85 @@ func (r *ListSourcemapsOptionalParameters) WithFilterFileHash(filterFileHash str
}

// ListSourcemaps List source maps.
// Retrieves a paginated list of source maps matching the specified filter criteria.
// Retrieves a paginated list of source maps. Send filters as query parameters,
// not in a JSON request body. `mapkind` defaults to `js`.
//
// For JavaScript source maps, choose one of these searches:
//
// - **Service and version:** provide both `filter[service]` and `filter[version]`.
// This searches source maps indexed by service and version.
// - **One debug ID:** provide `filter[debug_id]` with a UUID to look up the single
// source map with that debug ID. Service and version are not required for this
// JavaScript search.
// - **Browse debug IDs:** set `search_by=debug_id` to list source maps indexed by
// debug ID without specifying an ID. Do not send service, version, or filename
// filters in this mode.
//
// **Pagination:** for JavaScript listings, omit `page[after]` and `page[number]`
// to start at the first page. Copy `meta.page.next_cursor` into `page[after]` on
// the next request, keeping the same search mode and filters. Continue until
// `meta.page.has_more_results` is `false`. Do not decode or modify the cursor.
// Debug-ID browsing requires cursor pagination; `page[number]` is not supported.
// A specific `filter[debug_id]` lookup without `search_by=debug_id` does not support
// `page[after]`. Other map kinds use `page[number]`, starting at 1.
//
// **Examples:** the following commands use the US1 API host. Replace the host with
// the API host for your site, and the service, version, debug ID, and cursor with
// values from your organization. Use `--get` so curl sends the filters in the query
// string; `-X GET` with `--data-urlencode` sends them in the request body instead.
//
// **List by service and version**
//
// ```bash
//
// curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
// -H "Accept: application/json" \
// -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
// --data-urlencode "mapkind=js" \
// --data-urlencode "filter[service]=my-web-service" \
// --data-urlencode "filter[version]=1.0.0" \
// --data-urlencode "page[size]=10"
//
// ```
//
// **Find a specific JavaScript debug ID**
//
// ```bash
//
// curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
// -H "Accept: application/json" \
// -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
// --data-urlencode "mapkind=js" \
// --data-urlencode "filter[debug_id]=00000000-0000-4000-8000-000000000001"
//
// ```
//
// **Browse debug-ID source maps from the first page**
//
// ```bash
//
// curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
// -H "Accept: application/json" \
// -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
// --data-urlencode "mapkind=js" \
// --data-urlencode "search_by=debug_id" \
// --data-urlencode "page[size]=10"
//
// ```
//
// **Get the next page of debug-ID source maps**
//
// ```bash
//
// curl -sS --get "https://api.datadoghq.com/api/v2/sourcemaps/list" \
// -H "Accept: application/json" \
// -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
// --data-urlencode "mapkind=js" \
// --data-urlencode "search_by=debug_id" \
// --data-urlencode "page[size]=10" \
// --data-urlencode "page[after]=<meta.page.next_cursor>"
//
// ```
func (a *RUMApi) ListSourcemaps(ctx _context.Context, o ...ListSourcemapsOptionalParameters) (ListSourcemapsResponse, *_nethttp.Response, error) {
var (
localVarHTTPMethod = _nethttp.MethodGet
Expand Down Expand Up @@ -1411,9 +1504,15 @@ func (a *RUMApi) ListSourcemaps(ctx _context.Context, o ...ListSourcemapsOptiona
localVarHeaderParams := make(map[string]string)
localVarQueryParams := _neturl.Values{}
localVarFormParams := _neturl.Values{}
if optionalParams.SearchBy != nil {
localVarQueryParams.Add("search_by", datadog.ParameterToString(*optionalParams.SearchBy, ""))
}
if optionalParams.Mapkind != nil {
localVarQueryParams.Add("mapkind", datadog.ParameterToString(*optionalParams.Mapkind, ""))
}
if optionalParams.PageAfter != nil {
localVarQueryParams.Add("page[after]", datadog.ParameterToString(*optionalParams.PageAfter, ""))
}
if optionalParams.PageSize != nil {
localVarQueryParams.Add("page[size]", datadog.ParameterToString(*optionalParams.PageSize, ""))
}
Expand Down
Loading
Loading