Skip to content

docs(api-reference): drop nonexistent success/meta.* fields from envelope (SHA-3208) #231

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

Merged
paperclip-resolver merged 1 commit into from
May 21, 2026
Merged

docs(api-reference): drop nonexistent success/meta.* fields from envelope (SHA-3208) #231

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
46 changes: 14 additions & 32 deletions content/de/api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,12 @@ SharpAPI bietet 35 Routen über 7 Namespaces hinweg, zuzüglich Referenz- und He

## Response-Format

### Erfolgs-Envelope
Zwei Formen auf oberster Ebene — beide stellen `data` an den Anfang und `updated_at` ans Ende, mit einem optionalen `pagination`-Block dazwischen. Es gibt **kein** `success`-Feld; der HTTP-Statuscode ist die Quelle der Wahrheit. Siehe [Response Conventions](/de/api-reference/conventions) für das vollständige Regelwerk.

Alle erfolgreichen Antworten verpacken Daten in einem konsistenten Envelope:
### Paginierte Listen-Antwort

```json
{
"success": true,
"data": [
{
"id": "draftkings_33483153_moneyline_PHO",
Expand All @@ -140,59 +139,42 @@ Alle erfolgreichen Antworten verpacken Daten in einem konsistenten Envelope:
"pagination": {
"limit": 50,
"offset": 0,
"count": 1,
"total": 3095,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"meta": {
"count": 1,
"total": 3095,
"pagination": {
"limit": 50,
"offset": 0,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"updated_at": "2026-01-26T02:10:37.846Z",
"filters": {
"sportsbook": "draftkings",
"league": "nba"
}
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

| Feld | Beschreibung |
|------|--------------|
| `success` | `true` für alle erfolgreichen Antworten |
| `data` | Array von Ergebnissen (oder einzelnes Objekt für Detail-Endpoints) |
| `data` | Array von Ergebnissen |
| `pagination.limit` | Maximale Anzahl von Elementen pro Seite (Standard: 50, Max: 200) |
| `pagination.offset` | Aktueller Offset in den Ergebnissen |
| `pagination.count` | Anzahl der in dieser Antwort zurückgegebenen Elemente |
| `pagination.total` | Gesamtanzahl übereinstimmender Elemente über alle Seiten hinweg. Wird auf Endpoints weggelassen, die das nicht günstig berechnen können (z. B. `/odds`). |
| `pagination.has_more` | Ob weitere Ergebnisse über diese Seite hinaus existieren |
| `pagination.next_offset` | Offset-Wert für die nächste Seite (veraltet — verwenden Sie `next_cursor` für Live-Daten-Endpoints) |
| `pagination.next_cursor` | Opaker Cursor für die nächste Seite. Übergeben als `?cursor=` — stabil gegenüber Live-Datenänderungen. Empfohlen für mehrseitige Scans. |
| `meta.count` | Anzahl der in dieser Antwort zurückgegebenen Elemente |
| `meta.total` | Gesamtanzahl übereinstimmender Elemente über alle Seiten hinweg |
| `meta.pagination` | Identisch mit dem `pagination` auf oberster Ebene (zur Abwärtskompatibilität enthalten) |
| `meta.updated_at` | ISO 8601-Zeitstempel der letzten Datenaktualisierung |
| `meta.filters` | Echo der auf diese Anfrage angewendeten Filter |
| `pagination.next_offset` | Offset-Wert für die nächste Seite. Bevorzugen Sie `next_cursor` auf Live-Daten-Endpoints. |
| `pagination.next_cursor` | Opaker Cursor für die nächste Seite. Übergeben als `?cursor=` — stabil gegenüber Live-Datenänderungen. Empfohlen für mehrseitige Scans. Nur auf Cursor-fähigen Endpoints (`/odds`, `/odds/delta`) vorhanden. |
| `updated_at` | ISO 8601-Zeitstempel der letzten Datenaktualisierung |

### Antwort für einzelne Ressource

Wird für Einzelressourcen (`/account`, `/events/:eventId`) und nicht-paginierte Referenz-Endpoints verwendet. Kein `pagination`-Block.

```json
{
"success": true,
"data": {
"id": "evt_abc123",
"sport": "nba",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"start_time": "2026-01-26T19:00:00Z"
},
"meta": {
"updated_at": "2026-01-26T02:10:37.846Z"
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

Expand Down
48 changes: 15 additions & 33 deletions content/en/api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,12 @@ SharpAPI exposes 35 routes across 7 namespaces plus reference and health endpoin

## Response Format

### Success Envelope
Two top-level shapes — both put `data` first and `updated_at` last, with an optional `pagination` block in between. There is **no** `success` field; the HTTP status code is the source of truth. See [Response Conventions](/en/api-reference/conventions) for the full rule set.

All successful responses wrap data in a consistent envelope:
### Paginated list response

```json
{
"success": true,
"data": [
{
"id": "draftkings_33483153_moneyline_PHO",
Expand All @@ -140,59 +139,42 @@ All successful responses wrap data in a consistent envelope:
"pagination": {
"limit": 50,
"offset": 0,
"count": 1,
"total": 3095,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"meta": {
"count": 1,
"total": 3095,
"pagination": {
"limit": 50,
"offset": 0,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"updated_at": "2026-01-26T02:10:37.846Z",
"filters": {
"sportsbook": "draftkings",
"league": "nba"
}
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

| Field | Description |
|-------|-------------|
| `success` | `true` for all successful responses |
| `data` | Array of results (or single object for detail endpoints) |
| `data` | Array of results |
| `pagination.limit` | Maximum items per page (default: 50, max: 200) |
| `pagination.offset` | Current offset into results |
| `pagination.count` | Number of items returned in this response |
| `pagination.total` | Total matching items across all pages. Omitted on endpoints that can't compute it cheaply (e.g. `/odds`). |
| `pagination.has_more` | Whether more results exist beyond this page |
| `pagination.next_offset` | Offset value to use for the next page (legacy — use `next_cursor` for live-data endpoints) |
| `pagination.next_cursor` | Opaque cursor for the next page. Pass as `?cursor=` — stable against live data changes. Recommended for multi-page scans. |
| `meta.count` | Number of items returned in this response |
| `meta.total` | Total matching items across all pages |
| `meta.pagination` | Same as top-level `pagination` (included for backward compatibility) |
| `meta.updated_at` | ISO 8601 timestamp of when the data was last refreshed |
| `meta.filters` | Echo of the filters applied to this request |
| `pagination.next_offset` | Offset value to use for the next page. Prefer `next_cursor` on live-data endpoints. |
| `pagination.next_cursor` | Opaque cursor for the next page. Pass as `?cursor=` — stable against live data changes. Recommended for multi-page scans. Present only on cursor-supporting endpoints (`/odds`, `/odds/delta`). |
| `updated_at` | ISO 8601 timestamp of when the data was last refreshed |

### Single Resource Response
### Single resource response

Used for singletons (`/account`, `/events/:eventId`) and non-paginated reference endpoints. No `pagination` block.

```json
{
"success": true,
"data": {
"id": "evt_abc123",
"sport": "nba",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"start_time": "2026-01-26T19:00:00Z"
},
"meta": {
"updated_at": "2026-01-26T02:10:37.846Z"
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

Expand Down
46 changes: 14 additions & 32 deletions content/es/api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,12 @@ SharpAPI expone 35 rutas en 7 espacios de nombres, además de endpoints de refer

## Formato de la respuesta

### Envoltura de éxito
Dos formas en el nivel superior: ambas colocan `data` primero y `updated_at` al final, con un bloque `pagination` opcional en medio. **No** existe el campo `success`; el código de estado HTTP es la fuente de verdad. Consulta [Convenciones de respuesta](/es/api-reference/conventions) para el conjunto completo de reglas.

Todas las respuestas correctas envuelven los datos en una envoltura coherente:
### Respuesta de lista paginada

```json
{
"success": true,
"data": [
{
"id": "draftkings_33483153_moneyline_PHO",
Expand All @@ -140,59 +139,42 @@ Todas las respuestas correctas envuelven los datos en una envoltura coherente:
"pagination": {
"limit": 50,
"offset": 0,
"count": 1,
"total": 3095,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"meta": {
"count": 1,
"total": 3095,
"pagination": {
"limit": 50,
"offset": 0,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"updated_at": "2026-01-26T02:10:37.846Z",
"filters": {
"sportsbook": "draftkings",
"league": "nba"
}
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

| Campo | Descripción |
|-------|-------------|
| `success` | `true` para todas las respuestas correctas |
| `data` | Array de resultados (u objeto único en endpoints de detalle) |
| `data` | Array de resultados |
| `pagination.limit` | Número máximo de elementos por página (predeterminado: 50, máximo: 200) |
| `pagination.offset` | Desplazamiento actual dentro de los resultados |
| `pagination.count` | Número de elementos devueltos en esta respuesta |
| `pagination.total` | Total de elementos coincidentes en todas las páginas. Se omite en endpoints que no pueden calcularlo de forma barata (por ejemplo, `/odds`). |
| `pagination.has_more` | Indica si existen más resultados más allá de esta página |
| `pagination.next_offset` | Valor de desplazamiento para la siguiente página (heredado: utiliza `next_cursor` para endpoints con datos en vivo) |
| `pagination.next_cursor` | Cursor opaco para la siguiente página. Pásalo como `?cursor=`: es estable frente a cambios en datos en vivo. Recomendado para recorridos de varias páginas. |
| `meta.count` | Número de elementos devueltos en esta respuesta |
| `meta.total` | Total de elementos coincidentes en todas las páginas |
| `meta.pagination` | Igual que `pagination` en el nivel superior (incluido por compatibilidad retroactiva) |
| `meta.updated_at` | Marca de tiempo ISO 8601 de la última actualización de los datos |
| `meta.filters` | Reflejo de los filtros aplicados a esta solicitud |
| `pagination.next_offset` | Valor de desplazamiento para la siguiente página. Prefiere `next_cursor` en endpoints con datos en vivo. |
| `pagination.next_cursor` | Cursor opaco para la siguiente página. Pásalo como `?cursor=`: es estable frente a cambios en datos en vivo. Recomendado para recorridos de varias páginas. Solo aparece en endpoints que admiten cursor (`/odds`, `/odds/delta`). |
| `updated_at` | Marca de tiempo ISO 8601 de la última actualización de los datos |

### Respuesta de un único recurso

Se utiliza para recursos individuales (`/account`, `/events/:eventId`) y endpoints de referencia no paginados. Sin bloque `pagination`.

```json
{
"success": true,
"data": {
"id": "evt_abc123",
"sport": "nba",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"start_time": "2026-01-26T19:00:00Z"
},
"meta": {
"updated_at": "2026-01-26T02:10:37.846Z"
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

Expand Down
46 changes: 14 additions & 32 deletions content/pt-BR/api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,12 @@ A SharpAPI expõe 35 rotas em 7 namespaces, além de endpoints de referência e

## Formato da Resposta

### Envelope de Sucesso
Duas formas de nível superior — ambas colocam `data` primeiro e `updated_at` por último, com um bloco `pagination` opcional no meio. **Não** existe campo `success`; o código de status HTTP é a fonte da verdade. Consulte [Convenções de Resposta](/pt-BR/api-reference/conventions) para o conjunto completo de regras.

Todas as respostas bem-sucedidas encapsulam os dados em um envelope consistente:
### Resposta de lista paginada

```json
{
"success": true,
"data": [
{
"id": "draftkings_33483153_moneyline_PHO",
Expand All @@ -140,59 +139,42 @@ Todas as respostas bem-sucedidas encapsulam os dados em um envelope consistente:
"pagination": {
"limit": 50,
"offset": 0,
"count": 1,
"total": 3095,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"meta": {
"count": 1,
"total": 3095,
"pagination": {
"limit": 50,
"offset": 0,
"has_more": true,
"next_offset": 50,
"next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
},
"updated_at": "2026-01-26T02:10:37.846Z",
"filters": {
"sportsbook": "draftkings",
"league": "nba"
}
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

| Campo | Descrição |
|-------|-----------|
| `success` | `true` para todas as respostas bem-sucedidas |
| `data` | Array de resultados (ou objeto único para endpoints de detalhe) |
| `data` | Array de resultados |
| `pagination.limit` | Máximo de itens por página (padrão: 50, máximo: 200) |
| `pagination.offset` | Offset atual nos resultados |
| `pagination.count` | Número de itens retornados nesta resposta |
| `pagination.total` | Total de itens correspondentes em todas as páginas. Omitido em endpoints que não conseguem calculá-lo de forma barata (por exemplo, `/odds`). |
| `pagination.has_more` | Indica se existem mais resultados além desta página |
| `pagination.next_offset` | Valor de offset a ser usado para a próxima página (legado — use `next_cursor` para endpoints de dados em tempo real) |
| `pagination.next_cursor` | Cursor opaco para a próxima página. Passe como `?cursor=` — estável contra alterações de dados em tempo real. Recomendado para varreduras de múltiplas páginas. |
| `meta.count` | Número de itens retornados nesta resposta |
| `meta.total` | Total de itens correspondentes em todas as páginas |
| `meta.pagination` | O mesmo que o `pagination` de nível superior (incluído para compatibilidade retroativa) |
| `meta.updated_at` | Timestamp ISO 8601 indicando quando os dados foram atualizados pela última vez |
| `meta.filters` | Eco dos filtros aplicados a esta requisição |
| `pagination.next_offset` | Valor de offset a ser usado para a próxima página. Prefira `next_cursor` em endpoints de dados em tempo real. |
| `pagination.next_cursor` | Cursor opaco para a próxima página. Passe como `?cursor=` — estável contra alterações de dados em tempo real. Recomendado para varreduras de múltiplas páginas. Presente apenas em endpoints com suporte a cursor (`/odds`, `/odds/delta`). |
| `updated_at` | Timestamp ISO 8601 indicando quando os dados foram atualizados pela última vez |

### Resposta de Recurso Único

Usada para recursos únicos (`/account`, `/events/:eventId`) e endpoints de referência não paginados. Sem bloco `pagination`.

```json
{
"success": true,
"data": {
"id": "evt_abc123",
"sport": "nba",
"home_team": "PHI 76ers",
"away_team": "PHO Suns",
"start_time": "2026-01-26T19:00:00Z"
},
"meta": {
"updated_at": "2026-01-26T02:10:37.846Z"
}
"updated_at": "2026-01-26T02:10:37.846Z"
}
```

Expand Down