feat: how to acquire an SAT

.github/workflows/dispatch.yml

@@ -0,0 +1,33 @@
+name: Manually publish documentation
+
+on: workflow_dispatch
+
+jobs:
+  build_deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs
+          pip install mkdocs-dracula-theme
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - name: Build docs
+        run: |
+          mkdocs build
+      - name: Deploy docs to S3 bucket
+        uses: jakejarvis/[email protected]
+        with:
+          args: --follow-symlinks --delete
+        env:
+          AWS_S3_BUCKET: 'origin-osaas-api-docs'
+          AWS_ACCESS_KEY_ID: ${{ secrets.S3_AWS_ACCESS_KEY_ID  }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: 'eu-north-1'
+          SOURCE_DIR: 'site/'

.gitignore

@@ -0,0 +1 @@
+site/

docs/index.md

@@ -0,0 +1,32 @@
+Welcome to Eyevinn Open Source Cloud API documentation
+
+## Getting Started
+
+To access the APIs for the services running in Eyevinn Open Source Cloud you need a Service Access Token (SAT). The SATs are unique for each type of service. To obtain an SAT you will be using the Personal Access Token (PAT) that you have previously received by your sales representative at Eyevinn.
+
+### Example: Acquire an SAT for FAST Engine as a Service
+
+In this example we are using `curl` to show you how to get an SAT for FAST Engine as a Service.
+
+```
+curl -X 'POST' \
+  'https://token.svc.prod.osaas.io/servicetoken' \
+  -H 'accept: application/json' \
+  -H 'x-pat-jwt: Bearer <PAT>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "serviceId": "channel-engine"
+}'
+```
+
+The service identifier for the FAST Engine as a Service is `channel-engine`. In response you will get something like this:
+
+```json
+{
+  "serviceId": "channel-engine",
+  "token": "<SAT>",
+  "expiry": 1699462522
+}
+```
+
+The SAT is the value of the `token` in the JSON response above and what you will be using when creating and removing FAST Engine channels.

docs/services/channel-engine.md

@@ -0,0 +1,139 @@
+## Open Source FAST Engine as a Service API
+
+To create and remove channels a REST API is available and API documentation is [available online](https://api-ce.prod.osaas.io/docs). To access the API you need a Service Access Token that you acquire with your [Personal Access Token](../index.md). To request a personal access token or get more information about the service contact [[email protected]](mailto:[email protected]). If you want to try it out first we have a test environment available that you can use. See further down below on how to get access to the test environment.
+
+## Create a channel from looping a VOD
+
+Create a channel by looping a VOD with this command. Replace `SAT` with the the Service Access Token you have acquire
+.
+
+```bash
+curl -X 'POST' \
+  'https://api-ce.prod.osaas.io/channel' \
+  -H 'accept: application/json' \
+  -H 'x-jwt: Bearer SAT' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "name": "mychannel",
+  "type": "Loop",
+  "url": "https://testcontent.eyevinn.technology/vinn/cmaf/index.m3u8"
+}'
+```
+
+In return you will get:
+
+```json
+{
+  "id": "eyevinn-mychannel",
+  "name": "mychannel",
+  "type": "Loop",
+  "url": "https://testcontent.eyevinn.technology/vinn/cmaf/index.m3u8",
+  "playback": "https://eyevinn.ce.prod.osaas.io/channels/mychannel/master.m3u8"
+}
+```
+
+The channel's playback URL is [https://eyevinn.ce.prod.osaas.io/channels/mychannel/master.m3u8](https://web.player.eyevinn.technology/?manifest=https%3A%2F%2Feyevinn.ce.prod.osaas.io%2Fchannels%2Fmychannel%2Fmaster.m3u8)
+
+## Create a channel with ad insertion opportunity
+
+To demonstrate how to insert an opportunity to place ads in a FAST channel you can place a preroll / ad-slate before each VOD. The FAST channel will be decorated with HLS ad tags that a Server-Side Ad Inserter will utilize to replace with ads from the inventory.
+
+```bash
+curl -X 'POST' \
+  'https://api-ce.prod.osaas.io/channel' \
+  -H 'accept: application/json' \
+  -H 'x-jwt: Bearer SAT' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "name": "houseads",
+  "type": "Loop",
+  "url": "https://testcontent.eyevinn.technology/vinn/cmaf/index.m3u8",
+  "opts": {
+    "preroll": {
+      "url": "https://testcontent.eyevinn.technology/reel/cmaf/index.m3u8",
+      "duration": "127"
+    }
+  }
+}'
+```
+
+## Create a channel using a webhook
+
+To create a channel that uses a custom webhook you can run the following command.
+
+```bash
+curl -X 'POST' \
+  'https://api-ce.prod.osaas.io/channel' \
+  -H 'accept: application/json' \
+  -H 'x-jwt: Bearer SAT' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "name": "mychannel",
+  "type": "WebHook",
+  "url": "https://nextvod.dev.eyevinn.technology"
+}'
+```
+
+Where you would replace the `https://nextvod.dev.eyevinn.technology` with the URL to your webhook. For more information and example of a webhook read the [webhook-plugin documentation](https://fast.docs.eyevinn.technology/plugins/webhook.html).
+
+## Remove a channel
+
+To remove a channel you run the following and replace the `eyevinn-mychannel` with the channel id of your channel.
+
+```bash
+curl -X 'DELETE' \
+  'https://api-ce.prod.osaas.io/channel/eyevinn-mychannel' \
+  -H 'accept: application/json' \
+  -H 'x-jwt: Bearer SAT'
+```
+
+## List all your channels
+
+To list all the channels that you have created run the following command. Replace `SAT` with your token.
+
+```bash
+curl -X 'GET' \
+  'https://api-ce.prod.osaas.io/channel' \
+  -H 'accept: application/json' \
+  -H 'x-jwt: Bearer SAT'
+```
+
+In return you should get something like this.
+
+```json
+[
+  {
+    "id":"eyevinn-houseads",
+    "name":"houseads",
+    "type":"Loop",
+    "url":"https://eyevinn.ce.prod.osaas.io/channels/houseads/master.m3u8"
+  },
+  {
+    "id":"eyevinn-mychannel",
+    "name":"mychannel",
+    "type":"Loop",
+    "url":"https://eyevinn.ce.prod.osaas.io/channels/mychannel/master.m3u8"
+    }
+]
+```
+
+## Test Environment
+
+The address to the API in the test environment is `https://api-ce.stage.osaas.io/docs` and here you can generate a trial-token to try this out. Replace `api-ce.prod.osaas.io` in the instructions above with `api-ce.stage.osaas.io` in the API calls.
+
+### Create trial-token
+
+Generate a trial-token in our demo environment. The trial-token limits you to maximum of 3 channels and running in our test environment. Replace `YOUR_ORG` and `YOUR_EMAIL` in the command below.
+
+```bash
+curl -X 'POST' \
+  'https://api-ce.stage.osaas.io/token' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "company": "YOUR_ORG",
+  "email": "YOUR_EMAIL"
+}'
+```
+
+In return you get a trial `SAT` that you will be using to create and remove channels in our demo environment.

mkdocs.yml

@@ -0,0 +1,12 @@
+site_name: Eyevinn Open Source Cloud API
+site_url: https://docs.osaas.io
+site_description: API Documentation for Eyevinn Open Source Cloud
+site_author: Eyevinn Technology
+nav:
+  - Home: index.md
+  - APIs:
+    - FAST Engine API: services/channel-engine.md
+theme:
+  name: dracula
+
+copyright: Copyright &copy; 2023- <a href="https://www.eyevinn.se">Eyevinn Technology AB</a>