Skip to content

Commit a83bbe2

Browse files
MaartenRimauxdevin-ai-integration[bot]
MaartenRimaux
and
devin-ai-integration[bot]
authored
Ads docs v2 (#817)
Co-authored-by: Devin AI <devin-ai-integration[bot]@users.noreply.github.com>
1 parent d8d9e53 commit a83bbe2

159 files changed

Lines changed: 71514 additions & 543 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/update-ads-api-docs.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Update Ads API reference
2+
on:
3+
# Triggered from the Ads service repository whenever its OpenAPI contract changes:
4+
# gh api repos/THEOplayer/documentation/dispatches -f event_type=update-ads-api-docs
5+
repository_dispatch:
6+
types: [update-ads-api-docs]
7+
workflow_dispatch:
8+
jobs:
9+
update:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: write
13+
pull-requests: write
14+
env:
15+
# The branch that will receive the regenerated API reference (will be created if it doesn't exist)
16+
# Will automatically open a new PR (if no PR exists yet)
17+
UPDATE_BRANCH: update-ads-api-docs
18+
steps:
19+
- name: Create app token
20+
uses: actions/create-github-app-token@v3
21+
id: app-token
22+
with:
23+
client-id: ${{ vars.THEOPLAYER_BOT_CLIENT_ID }}
24+
private-key: ${{ secrets.THEOPLAYER_BOT_PRIVATE_KEY }}
25+
- name: Checkout
26+
uses: actions/checkout@v7
27+
with:
28+
token: ${{ steps.app-token.outputs.token }}
29+
fetch-depth: 1
30+
- name: Configure Git user
31+
run: |
32+
git config user.name 'theoplayer-bot[bot]'
33+
git config user.email '873105+theoplayer-bot[bot]@users.noreply.github.com'
34+
- name: Create or checkout update branch
35+
# language=bash
36+
run: |
37+
if git fetch --depth 1 origin refs/heads/$UPDATE_BRANCH ; then
38+
git checkout -b $UPDATE_BRANCH FETCH_HEAD
39+
else
40+
git checkout -b $UPDATE_BRANCH HEAD
41+
fi
42+
- name: Setup Node.JS
43+
uses: actions/setup-node@v7
44+
with:
45+
node-version: '24'
46+
cache: 'npm'
47+
cache-dependency-path: ./package-lock.json
48+
- name: Install dependencies
49+
run: npm ci
50+
- name: Regenerate Ads API reference
51+
run: npm run refresh-ads-api-docs
52+
- name: Check for changes
53+
id: check_changes
54+
# language=bash
55+
run: |
56+
if [[ -z "$(git status --porcelain ads/api/reference)" ]]; then
57+
echo "No API reference changes detected."
58+
else
59+
echo "changed=true" >> "$GITHUB_OUTPUT"
60+
fi
61+
- name: Commit and push changes
62+
if: ${{ steps.check_changes.outputs.changed }}
63+
# language=bash
64+
run: |
65+
git add ads/api/reference
66+
git commit -m 'Update Ads API reference'
67+
git push --force origin HEAD:$UPDATE_BRANCH
68+
- name: Check if pull request already exists
69+
if: ${{ steps.check_changes.outputs.changed }}
70+
id: check_pr_exists
71+
# language=bash
72+
run: |
73+
pr_count=$(gh pr list --base main --head "$UPDATE_BRANCH" --state open --limit 1 --json number --jq length)
74+
if ((pr_count > 0)); then
75+
echo "exists=true" >> "$GITHUB_OUTPUT"
76+
fi
77+
env:
78+
GH_TOKEN: ${{ steps.app-token.outputs.token }}
79+
- name: Create pull request
80+
if: ${{ steps.check_changes.outputs.changed && !steps.check_pr_exists.outputs.exists }}
81+
# language=bash
82+
run: |
83+
gh pr create \
84+
--base main \
85+
--head "$UPDATE_BRANCH" \
86+
--title "Update Ads API reference" \
87+
--body "This PR regenerates the OptiView Ads API reference from the latest OpenAPI contract."
88+
env:
89+
GH_TOKEN: ${{ steps.app-token.outputs.token }}

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ theoplayer_versioned_docs/*/changelog.md
1717
theoplayer_versioned_docs/*/static/theoplayer/*/api-reference
1818
ads/api/ads-client.swagger.json
1919
ads/api/signaling/
20+
ads_versioned_docs/*/api/
2021
adengine/static/ad-engine.yaml
2122
adengine/reference/
2223
millicast/api/

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,25 @@ If you're looking to contribute to the developer documentation itself, see https
1818
1. `npm install` on first usage
1919
2. `git submodule update --init` to install submodules
2020
3. `npm start` to open in dev mode
21+
22+
### Ads API reference
23+
24+
The V2 Ads API reference is generated from the public OpenAPI document served
25+
by the Ads API (`https://us.ads.optiview.dolby.com/api/v1/docs/json`). The
26+
generated MDX pages are committed, but the fetched spec is not.
27+
28+
The reference is kept in sync by the `update-ads-api-docs` workflow: the Ads
29+
service repository triggers a `repository_dispatch` event (type
30+
`update-ads-api-docs`) whenever its contract changes, and the workflow
31+
regenerates the pages and opens a PR. It can also be run manually from the
32+
Actions tab.
33+
34+
To refresh locally:
35+
36+
```bash
37+
npm run refresh-ads-api-docs
38+
npm run build
39+
```
40+
41+
Use `ADS_OPENAPI_SPEC_URL` to point at another URL or a local
42+
`/path/to/openapi.json`.

‎ads/api/index.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Ads REST API
3+
sidebar_label: REST API
4+
---
5+
6+
# Ads REST API
7+
8+
The Ads REST API manages channels, origins, marker rules, breaks, events, templates, and integrations under `/api/v1`.
9+
10+
## Authentication
11+
12+
Every request requires both:
13+
14+
- HTTP Basic authentication, with the API key as the username and API secret as the password.
15+
- The `X-Org-ID` header identifying the organization.
16+
17+
```bash
18+
curl 'https://us.ads.optiview.dolby.com/api/v1/channels' \
19+
-u "$ADS_API_KEY:$ADS_API_SECRET" \
20+
-H 'X-Org-ID: <org-id>'
21+
```
22+
23+
Treat the secret like a password. The internal service authentication used between platform components is not a public API authentication method.
24+
25+
## Reference
26+
27+
Browse the [generated Ads REST API reference](/ads/api/reference/optiview-ads-api). Operations are grouped by resource.

‎ads/api/reference/delete-channels-channel-id-breaks-break-id.api.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
id: delete-channels-channel-id-breaks-break-id
3+
title: 'Delete /channels/{channelId}/breaks/{breakId}'
4+
description: 'Delete a break.'
5+
sidebar_label: 'Delete /channels/{channelId}/breaks/{breakId}'
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJytVMtu2zAQ/BViTw5AW03Rk24u4oPRAgnSx8XwYS2uLSIyxZArJ67Afy9WlmzHaYO26Emv3ZnZGS1bMBSLYD3b2kEON1QRk0K1CoQPE9DgMeCWmEKEfNFCLEraIuQt8N4T5BA5WLeBpMEKgEcuQYPDrXwsSnSOqrkBDYEeGxvIQM6hIX1BPDfk2K4tBVWvFZek+t4JJP23tJ34fyLtx05LaY2+dpGisL5/90Eul2atsalY3feVkJKG2lNAKZgbyMF0fo77WeL4aMi4Y4rjk1TGjVgMH7sPsNSwJS7rE0oXBpeQQ4beZrvrbIDN2iNuyg7AWdsjJ9AQqWiC5X2X4AqjLaaNAC2WGuqwEaWLpcw8FH4Ruw+Tn5UfzS+ZvcB2VeK31MClu9O7uXqgvRo1kYIkc6XQGRWpCMRq5DHGpzqYK0l4kHGkQG8/0R76eEtCQ+EU8PO4DpuxNa84b8MGnf3RBaDsMd5JF41167qjsFwJyq1n+93Sk5qaqKZ3c9CwoxAPSLtrkeXryFt00tVT9xvyx96/0NdCUTsmx79ctX50pmfOfIXWiYImVNJ3SH4hvojMa9DDckXQkJ8v2kGEvB1+rqWGso4s/W27wkjfQpWSvH5sKOwPP8IOg8WVGLNowdgo9wbyNVbxcnHOxxjd9yt2pd7Y4d8MN4TtJOkdVo08gYYH2r84PeQI+E+S3nb7bUGDn2mZzrbzZvZ59nUGKf0ECTXMMw==
9+
sidebar_class_name: 'delete api-method'
10+
info_path: ads/api/reference/optiview-ads-api
11+
custom_edit_url: null
12+
hide_send_button: true
13+
---
14+
15+
import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
16+
import ParamsDetails from '@theme/ParamsDetails';
17+
import RequestSchema from '@theme/RequestSchema';
18+
import StatusCodes from '@theme/StatusCodes';
19+
import OperationTabs from '@theme/OperationTabs';
20+
import TabItem from '@theme/TabItem';
21+
import Heading from '@theme/Heading';
22+
import Translate from '@docusaurus/Translate';
23+
24+
<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/breaks/{breakId}'}></Heading>
25+
26+
<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/breaks/{breakId}'} context={'endpoint'}></MethodEndpoint>
27+
28+
Delete a break.
29+
30+
<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
31+
<Translate id="theme.openapi.request.title">Request</Translate>
32+
</Heading>
33+
34+
<ParamsDetails
35+
parameters={[
36+
{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' },
37+
{ schema: { type: 'string' }, in: 'path', name: 'breakId', required: true, description: 'Identifier of the break.' },
38+
]}
39+
></ParamsDetails>
40+
41+
<RequestSchema title={'Body'}></RequestSchema>
42+
43+
<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

‎ads/api/reference/delete-channels-channel-id-breaks.api.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
id: delete-channels-channel-id-breaks
3+
title: 'Delete /channels/{channelId}/breaks'
4+
description: 'Bulk delete breaks by IDs.'
5+
sidebar_label: 'Delete /channels/{channelId}/breaks'
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJyFVE1v2zAM/SsCTy2gJMuwk2/pkkOwAi26bpcgB8ZmbDW2pEpyUs/wfx/or6Tt2vliWyKp9x75VENCPnbKBmU0RHBT5geRUE6BxM4RHrzYVWK99FOQ4Oi5JB9uTFJBVLe/ylECUXAlSYiNDqQDb6G1uYqRi86ePFeuwccZFchfobIEEZjdE8UBJFhnLLmgyPOuStpXofQ6UOEhmsshA53DCiSobmOs5INTOgXJSbek05BBNG/kG27rhHRQe0XOC7MXIRspBtNznopFEDmhD8JoEsqLgeQUmkZeUN60OLdNw8sWHRYUyHmINv9g2uNrJCgGYjFkIEFjwZtxhlpTvk5AvpP0IwID/j53Cs2Wk7012ncqfv3yjV+vCyxpj2UexEMf2XJi7dtOrROIoNNh0hf2kxHdpNMKJARMmSfcdAtbCQWFzJyzuaVMMYIZWjU7zmdDuVk91mtmY0FPcelUqFrxduhVvCg5fbOVYFzKuDZbZjgE/mSBO54X4aPcWQiWy7ZREHUx8FbNxf1aHKgSV6Unx724FqgT4Sl2FMSVRe9PxiXXU+5bD2M8Aq36Qe0ocqmMMCF3bunLxLh0opJ3Z965FLX608ot1NjObrjYKA9ni61esLA5jZbYDGO0bedob1o4KnAI3Nmgfis6iUXixeJ+DRKO5Hx36nHOFKzxocDWij3MZefz/3TnFYP67PLP74pep0AvYWZzVJohlC7nEt1wbFhExjkHOZiAz4suDbEbZywzPnBSXe/Q0y+XNw0vP5fkqm5UjugU7liOTQ2J8vydQLTH3L+10iWNq4fedNfiE4N9wGgYB82zcMS85D+QcKDqlbUbblo/Jgyv2//egZg8cpVz/rvbs7n02HJ1u3pcsTb9PVyYhLMcnvgGwVOHwLRUW4+0azXkqNMSU47tqvLzF5xeDMU=
9+
sidebar_class_name: 'delete api-method'
10+
info_path: ads/api/reference/optiview-ads-api
11+
custom_edit_url: null
12+
hide_send_button: true
13+
---
14+
15+
import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
16+
import ParamsDetails from '@theme/ParamsDetails';
17+
import RequestSchema from '@theme/RequestSchema';
18+
import StatusCodes from '@theme/StatusCodes';
19+
import OperationTabs from '@theme/OperationTabs';
20+
import TabItem from '@theme/TabItem';
21+
import Heading from '@theme/Heading';
22+
import Translate from '@docusaurus/Translate';
23+
24+
<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/breaks'}></Heading>
25+
26+
<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/breaks'} context={'endpoint'}></MethodEndpoint>
27+
28+
Bulk delete breaks by IDs.
29+
30+
<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
31+
<Translate id="theme.openapi.request.title">Request</Translate>
32+
</Heading>
33+
34+
<ParamsDetails
35+
parameters={[{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' }]}
36+
></ParamsDetails>
37+
38+
<RequestSchema
39+
title={'Body'}
40+
body={{
41+
required: true,
42+
content: {
43+
'application/json': {
44+
schema: {
45+
type: 'object',
46+
properties: {
47+
ids: {
48+
minItems: 1,
49+
type: 'array',
50+
items: { type: 'string', minLength: 1 },
51+
description: 'Identifiers of the breaks to delete. At least one is required.',
52+
},
53+
},
54+
required: ['ids'],
55+
},
56+
},
57+
},
58+
}}
59+
></RequestSchema>
60+
61+
<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

‎ads/api/reference/delete-channels-channel-id-events-event-id.api.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
id: delete-channels-channel-id-events-event-id
3+
title: 'Delete /channels/{channelId}/events/{eventId}'
4+
description: 'Delete /channels/{channelId}/events/{eventId}'
5+
sidebar_label: 'Delete /channels/{channelId}/events/{eventId}'
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJytVMlu2zAQ/RViTjFAW3XRk24G7IPRAgnS5WL4QItji4hMMeRIiSvw34vR5qVF0QQ9aeHMe2/mzbABp7w6IqEPkG4aCFmORwVpA3RyCCkE8sYeIEowFlJwinKQYNWRD7NcWYvFWoMEj8+V8aghJV+hBI0h88aRKTlvrdGS2Rv0otwLylH0uTOI8q20WKOld5G2mTOIW04NrrQBA7N+/PCJH9fpS9yrqiDx2EdCjBJKh15xwFpDChoLJJz2tYTp2JBpyxSmZ6mkDtxiWLUHsL0Vu2yhRDJgJc0IFpMOLWl6uAgSjkh5edYAsmtSColyJqnn/wwUMKu8oVPr/04Fky0qBtpsJZT+wHVuttyxIfArm9X17SJ8tC4ncgzbRkHaxcBtuYuHtXjCk7irAnr2dSKU1SJg5pHEnVMhvJReT3g+BhkjhXLmM56gH44clUZ/Ho/XaekPU6N/47z3B2XNz9Y+YcbhmLXGGrsvWwpDBaPcOzI/DL6IhQ5i8bAGCTX60CHVc5blykBHZTmrp36riVf6xvIIXylxhTKWWSpf8Fnn7oZrZylzkMP6BZCQXq5iR8R/h/HbSsjLQJzfNDsV8LsvYuTfzxX6U2d2rbxROy5+04A2gd81pHtVhNvVaiArLaElSOHusV/CifjLlss/FzcYatnNWhUVf4GEJzxd3S98SfwnSf0d8C5BQz/jNl5s4HL1ZfVtBTH+Au5f0Mo=
9+
sidebar_class_name: 'delete api-method'
10+
info_path: ads/api/reference/optiview-ads-api
11+
custom_edit_url: null
12+
hide_send_button: true
13+
---
14+
15+
import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
16+
import ParamsDetails from '@theme/ParamsDetails';
17+
import RequestSchema from '@theme/RequestSchema';
18+
import StatusCodes from '@theme/StatusCodes';
19+
import OperationTabs from '@theme/OperationTabs';
20+
import TabItem from '@theme/TabItem';
21+
import Heading from '@theme/Heading';
22+
import Translate from '@docusaurus/Translate';
23+
24+
<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/events/{eventId}'}></Heading>
25+
26+
<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/events/{eventId}'} context={'endpoint'}></MethodEndpoint>
27+
28+
Delete /channels/\{channelId\}/events/\{eventId\}
29+
30+
<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
31+
<Translate id="theme.openapi.request.title">Request</Translate>
32+
</Heading>
33+
34+
<ParamsDetails
35+
parameters={[
36+
{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' },
37+
{ schema: { type: 'string' }, in: 'path', name: 'eventId', required: true, description: 'Identifier of the event.' },
38+
]}
39+
></ParamsDetails>
40+
41+
<RequestSchema title={'Body'}></RequestSchema>
42+
43+
<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

‎ads/api/reference/delete-channels-channel-id-events.api.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
id: delete-channels-channel-id-events
3+
title: 'Delete /channels/{channelId}/events'
4+
description: 'Delete /channels/{channelId}/events'
5+
sidebar_label: 'Delete /channels/{channelId}/events'
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJyNVMlu2zAQ/RViTglA23XRk25u44PRAAnS5WL4QItji4lEMuTIjivo34uhFmfrooskcubxvXkzbCDgY42RPjt9gqxJvyaghoxCjRJyZwkt8ZbyvjS5IuPs7D46y2sxL7BS/EUnj5CB295jTiDBB+cxkMHIu0anV2XsirCKkM3lkKFCUCeQYLqNESlSMHYPkpOu0e6pgGzeStAY82A804AMVhotmZ3BEIXbCSpQ4AEtRUFOaCyRcCoWJEpUkYSzKEwUg8gptK18JnmdeG7alpe9CqpCwhAhW7+jtOfXSjBMxCsqQIJVFW/mhbIWy5UG+aakfxIw8O9zp9BuODl6Z2NXxY8fPvHrJcAV7lRdkrjrI5Mmrn1yaqUhg64Okx44TkZ2k65WIIHUnnXCslvYvKZ5lSDEbMCYNSNIOxtRKqTCnU/kNuCyZDBT3swO83+kR8zrYOiUCr5V0eSLmtPXGwku7FnLesNVGQK/sSldbZ6FjxYVRJ5hUxRkXQy8lra4XYkHPImLOmJg/y6FslpEzAOSuPAqxqML+nLKXvc0xiOUN18xtS9DFag0hnMbPE1c2E+MfnPmTdgra34li4QZW6BrSB6uu/NYLp9U5Uscx2g9tN4m9d7OJTqGOARuPJmfBo9ioaNY3K5AwgFD7E49zFmCd5Eqlca3p/l/5r5QMBaA8IlmvlTGMnYdSt7rXF9zdZjAHOQwEQyUPZ8OHBuucJE4qWm2KuKPULYtLz/WGE5dDxxUMGrLOtcNaBP5W0O2U2V8PVfN+eaCi7t+Ai/FX6ZNvq9o8NmyyQdV1vwHEh7w9GLOW3aj95/pdftfOhKT74xyzn9zlXJTj8Nztbxefl+ChG1/KVdOc1ZQR75O1LFj4JLU1PxprYFS2X2t9hzbofLzG4ItBOU=
9+
sidebar_class_name: 'delete api-method'
10+
info_path: ads/api/reference/optiview-ads-api
11+
custom_edit_url: null
12+
hide_send_button: true
13+
---
14+
15+
import MethodEndpoint from '@theme/ApiExplorer/MethodEndpoint';
16+
import ParamsDetails from '@theme/ParamsDetails';
17+
import RequestSchema from '@theme/RequestSchema';
18+
import StatusCodes from '@theme/StatusCodes';
19+
import OperationTabs from '@theme/OperationTabs';
20+
import TabItem from '@theme/TabItem';
21+
import Heading from '@theme/Heading';
22+
import Translate from '@docusaurus/Translate';
23+
24+
<Heading as={'h1'} className={'openapi__heading'} children={'Delete /channels/{channelId}/events'}></Heading>
25+
26+
<MethodEndpoint method={'delete'} path={'/api/v1/channels/{channelId}/events'} context={'endpoint'}></MethodEndpoint>
27+
28+
Delete /channels/\{channelId\}/events
29+
30+
<Heading id={'request'} as={'h2'} className={'openapi-tabs__heading'}>
31+
<Translate id="theme.openapi.request.title">Request</Translate>
32+
</Heading>
33+
34+
<ParamsDetails
35+
parameters={[{ schema: { type: 'string' }, in: 'path', name: 'channelId', required: true, description: 'Identifier of the channel.' }]}
36+
></ParamsDetails>
37+
38+
<RequestSchema
39+
title={'Body'}
40+
body={{
41+
required: true,
42+
content: {
43+
'application/json': {
44+
schema: {
45+
type: 'object',
46+
properties: {
47+
ids: {
48+
minItems: 1,
49+
type: 'array',
50+
items: { type: 'string', minLength: 1 },
51+
description: 'Identifiers of the events to delete. At least one is required.',
52+
},
53+
},
54+
required: ['ids'],
55+
},
56+
},
57+
},
58+
}}
59+
></RequestSchema>
60+
61+
<StatusCodes responses={{ '204': { description: 'Default Response' } }}></StatusCodes>

0 commit comments

Comments
 (0)