Skip to content

Commit

Permalink
docs: add api auth, improve getting started, remove livestream
Browse files Browse the repository at this point in the history
  • Loading branch information
Yohan Totting committed Jul 9, 2024
1 parent 0078705 commit 4162d6e
Show file tree
Hide file tree
Showing 8 changed files with 108 additions and 1,166 deletions.
39 changes: 19 additions & 20 deletions content/docs/getting-started/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,37 +13,36 @@ menu:
weight: 2
---

# Getting started with inLive
# Getting Started with inLive

To start develop your app with inLive, you need to choose which API that fit with your usecase. This document will help you to choose which API that fit with your usecase.
To start developing your app with inLive, you need to choose the API that fits your use case. This document will help you select the most suitable API.

As explained before in the introduction, we have 2 products that you can use from total 3 products that we planned to build.
As mentioned in the introduction, we offer 2 products out of the 3 we plan to build:

1. Single input live streaming API that allows you to create a live stream and let others to watch with up to 2 second latency. This is based on CDN and HLS/Dash technology, which allow you to utilize the existing CDN infrastructure to deliver the video stream to million of viewers.
2. Multi input live streaming API, where you can create a live stream and invite others to join with less than 500ms latency. This is based on WebRTC Selective Forwarder Unit (SFU)technology, which allow you to develop a real-time interactive app like Google Meet or Zoom.
3. Video hosting API(still in design phase) that allows you to upload a video and the API will convert it to an optimal stream format, and store it in the cloud. This will allow you to develop a video on demand app like Youtube or Netflix.
1. **Single Input Live Streaming API**: Allows you to create a live stream and let others watch with up to 2-second latency. This is based on HLS/Dash technology, which allows you to utilize existing CDN infrastructure to deliver the video stream to millions of viewers.
2. **Multi Input Live Streaming API**: Enables you to create a live stream and invite others to join with less than 300ms latency. This is based on WebRTC Selective Forwarder Unit (SFU) technology, allowing you to develop real-time interactive apps like Google Meet or Zoom.
3. **Video Hosting API** (still in the design phase): Allows you to upload a video, and the API will convert it to an optimal stream format and store it in the cloud. This will enable you to develop a video-on-demand app like YouTube or Netflix.

From the product above, we can categorize the API into 2 categories:
From the products above, we can categorize the APIs into 2 categories:
1. Live video
2. Video on demand

We will only cover live video use case for now, and we will cover video on demand use case in the future when it's ready.
We will only cover the live video use case for now, and we will address the video on demand use case in the future when it's ready.

## Live video use cases
To help you choose which API that will fit with your use case, see these comparison:
## Live Video Use Cases
To help you choose the API that will fit your use case, see this comparison:

### Live Stream API - Single Input Live Streaming API
Use single input live streaming API if these condition is met:
Use the single input live streaming API if these conditions are met:

1. You like to build a single host live streaming app, where you only need to stream from one host and let others to watch, you can use our single input live streaming API. Example of this usecase is a live streaming app like Youtube Live or Twitch, live shopping app, or live event app.
1. You aim to build a single-host live streaming app, where you only need to stream from one host and let others watch. Examples of this use case include live streaming apps like YouTube Live or Twitch, live shopping apps, or live event apps.
2. A latency of 2 seconds is acceptable for your use case.
3. You want to be very cost efficient. This API estimated will cost you 1/5 of the cost of multi input live streaming API.
4. You want to live stream an offline event like concert, sport match, or conference where the performers are focus on offline interaction but you want to scale the audience by live streaming it online.
3. It's easy to embed everywhere using any HLS/Dash video players. You can embed the live stream on your website, mobile app, or even on your social media.
4. You want to live stream an offline event like a concert, sports match, or conference where the performers focus on offline interaction, but you want to scale the audience by live streaming it online.

### Hub API - Multi Input Live Streaming API
Use multi input live streaming API if these condition is met:
1. You want to develop a real-time interaction between the host and the audiences. Example of this usecase is a video call app, webinar app, or Google Meet/Zoom-like app.
2. There will be multiple hosts or video inputs in the same live stream.
3. You're okay with the cost is 5x more expensive than single input live streaming API. We're working to reduce the cost in the future.
### Real-time Communication API - Multiple Inputs and Real-time API
Use the multiple inputs real-time API if these conditions are met:
1. You want to develop real-time interaction between the host and the audience. Examples of this use case include a video call app, webinar app, or Google Meet/Zoom-like app.
2. There will be multiple hosts or video inputs in the same live stream. Examples of this use case include a webinar app with multiple speakers or a video call app with multiple participants.

Based on the comparison above you can choose which API that fit with your use case. Get started with the API that you choose by open the link below:
Based on the comparison above, you can choose the API that fits your use case. Get started with the API of your choice by following the link below:
42 changes: 42 additions & 0 deletions content/docs/getting-started/api-auth/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
date: 2024-07-08
lastmod: 2024-07-08
name: api-auth
title: API Authentication
description: Learn how to authenticate your application for access to Inlive APIs using an application key and access token.
ogimage: /images/docs/og-image.png
slug: api-auth
menu:
docs_sidebar:
identifier: api-auth
name: API Authentication
parent: getting-started
weight: 1
---

## Get an Application Key
To allow your app to access all Inlive APIs, you need an application key, also known as an API key. This application key is unique per application, and you will need to use it with all your API requests. Follow these steps to create your application key:
1. Register [an Inlive account](#).
2. Go to [the integration page](#).
3. Create an application key. Make sure you copy the key after you create it because you won't be able to see it again later.

## Authenticate Your API Request
The application key cannot be used directly with Inlive product APIs; instead, you need to generate an access token from the application key. The access token is a temporary token that will be used to authenticate your API requests. The access token will expire after a certain time, so you need to generate a new access token when the current one expires.

### Generate an Access Token
To generate an access token, you need to make a request to [the access token endpoint](https://api.inlive.app/apidocs/index.html#/apikeys/post_keys_accesstoken) with your application key. Here is an example of how to generate an access token using the `curl` command:
```bash
curl -X 'POST' \
'https://api.inlive.app/v1/keys/accesstoken' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-apikey-here>' \
-H 'Content-Type: application/json' \
-d '{
"expiry_seconds": 3600
}'
```

Use the access token as a bearer token in your API requests. Please note that although you can set the expiration time of the access token when you generate it, make sure not to set it too long as it could be a security risk. The recommended and default expiration time is 1 hour.

### Refresh an Access Token
The access token will expire after a certain time. All Inlive product APIs will validate your request using the validate endpoint. When the request returns an HTTP response code 403 Forbidden, and the response header has an X-Access-Token-Expired header, it means your access token has expired, and you need to refresh it. To refresh it, you need to generate a new access token as described above, using the same application key.
74 changes: 45 additions & 29 deletions content/docs/getting-started/using-hub-api/index.md
Original file line number Diff line number Diff line change
@@ -1,60 +1,76 @@
---
date: 2023-08-02
lastmod: 2023-08-02
lastmod: 2024-08-09
name: using-hub-api
title: Using Hub API
description:
title: Using the Hub API
description: Learn how to integrate the Hub API into your application for real-time online interactions.
ogimage: /images/docs/og-image.png
slug: using-hub-api
menu:
docs_sidebar:
identifier: using-hub-api
name: Using Hub API
name: Using the Hub API
parent: getting-started
weight: 2
---

# Using Hub API
# Using the Hub API

Learn how to use and integrate the Hub API into your application
Learn how to use and integrate the Hub API into your application for enabling real-time online interactions.

## About Hub API
## About the Hub API

The Hub API provides ways to enable real-time online interactions between multiple hosts and participants inside a room. It is built on top of WebRTC SFU (Selective Forwarding Unit) technology which will route the media stream from one peer to another peer in the same group with very low latency.
The Hub API facilitates real-time online interactions between multiple hosts and participants within a room. It leverages WebRTC SFU (Selective Forwarding Unit) technology to efficiently route media streams among peers in the same group, ensuring very low latency.

The current Hub API supports the basic features such as:
- Multi group, a possibility to create multi room for different group of peers.
- Group call, where all peers in the same group can send and receive media stream to each other.
- Real-time signaling channel, that enables client to receive an event from the channel server in a real-time.
- Perfect negotiation, enable to add additional track in the middle of the session such as screen sharing track.
The Hub API currently supports features such as:
- Multi-group capabilities, allowing the creation of multiple rooms for different groups of peers.
- Group calls, enabling all peers in the same group to send and receive media streams to and from each other.
- A real-time signaling channel, which allows clients to receive events from the channel server in real-time.
- Perfect negotiation, which allows the addition of extra tracks (e.g., for screen sharing) during an ongoing session.

## Making a request
## Making a Request

The Hub API can be accessed from `https://hub.inlive.app`. To make a request for a specific feature, you need to identify the specific API endpoint you want to use and provide any requirements that the endpoint may require. You can check our list of Hub API endpoints within our [API reference docs](https://hub.inlive.app/apidocs/index.html).
The Hub API is accessible at `https://hub.inlive.app`. To utilize a specific feature, identify the relevant API endpoint and provide the required parameters. Our [API reference documentation](https://hub.inlive.app/apidocs/index.html) lists all available Hub API endpoints.

### Your first room
## Authentication

You can start by making your first request to the create a room endpoint. Basically this endpoint will create a new room and returns a JSON response data about the new room. Using `curl` command, we can run and trigger our first request using HTTP `POST` method.
Accessing the Hub API requires authenticating your request with an access token. This temporary token authenticates your API requests but expires after a set period. When your access token expires, you will need to generate a new one. For instructions on generating an access token, refer to our [API authentication guide](/docs/getting-started/api-auth/).

### Creating Your First Room

Begin by creating a room using the endpoint for room creation. This endpoint generates a new room and returns JSON data about it. The following `curl` command demonstrates how to create a room using the HTTP `POST` method.

```bash
curl --request POST \
https://hub.inlive.app/v1/rooms/create \
--header 'Content-Type: application/json' \
--data '{ "name": "My room" }'
curl -X 'POST' \
'https://hub.inlive.app/v1/rooms/create' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-accesstoken-here>' \
-H 'Content-Type: application/json' \
-d '{
"name": "My Room"
}'
```

### Get the room data
### Retrieving Room Data

When the room is successfully created, you will receive a room `id` data which you can use it to run some available actions in the room. For example, you can get the data of the new room you just created by using the the room ID with this command.
Upon successful room creation, you'll receive a room ID. This ID can be used to perform actions within the room, such as retrieving the room's data with the following command:

```bash
curl --request GET \
https://hub.inlive.app/v1/rooms/<YOUR_ROOM_ID>
curl -X GET \
'https://hub.inlive.app/v1/rooms/<YOUR_ROOM_ID>' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-accesstoken-here>'
```

### Publishing and Subscribing to Media Streams

With an active room, you can publish and subscribe to media streams. Whether you're publishing a single media stream for others to subscribe to or subscribing to streams from others depends on your use case.

For a detailed guide on publishing and subscribing to media streams, refer to our tutorial on [developing a conference app with the Hub API](/docs/tutorials/hub-api/conference-app-with-hub-api/).

## Resources

- Read the [Hub API reference docs](https://hub.inlive.app/apidocs/index.html)
- Read an [example tutorial about developing a conference app](/docs/tutorials/hub-api/conference-app-with-hub-api/) using Hub API.
- Check out the [code example in GitHub](https://github.com/inlivedev/inlivedev.github.io/tree/main/examples/)
- Explore our open source [Hub SFU library in GitHub](https://github.com/inlivedev/sfu)
- Explore the [Hub API reference documentation](https://hub.inlive.app/apidocs/index.html).
- Follow an [example tutorial on developing a conference app](/docs/tutorials/hub-api/conference-app-with-hub-api/) with the Hub API.
- View [code examples on GitHub](https://github.com/inlivedev/inlivedev.github.io/tree/main/examples/).
- Discover our open-source [Inlive Hub SFU library on GitHub](https://github.com/inlivedev/sfu).
Loading

0 comments on commit 4162d6e

Please sign in to comment.