Skip to content

Commit

Permalink
chore(*): add security info for mobile clients and uploaders
Browse files Browse the repository at this point in the history
  • Loading branch information
@ThibaultBee
ThibaultBee committed Oct 23, 2023
1 parent 31ddde1 commit 986a786
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 99 deletions.
69 changes: 12 additions & 57 deletions templates/java/libraries/okhttp-gson/README.mustache
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,6 @@ Then manually install the following JARs:

Please follow the [installation](#installation) instruction and execute the following {{#android}}Kotlin{{/android}}{{^android}}Java{{/android}} code:

{{#client}}
{{^android}}
```java
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
Expand Down Expand Up @@ -114,59 +113,17 @@ public class Example {
{{/android}}
{{#android}}
```kotlin
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
val apiVideoClient = ApiVideoClient("YOUR_API_KEY")
// if you rather like to use the sandbox environment:
// val apiVideoClient = ApiVideoClient("YOU_SANDBOX_API_KEY", Environment.SANDBOX)

/**
* This example uses an Android specific API called WorkManager to dispatch upload.
* We initialize it before using it.
*/
VideosApiStore.initialize(apiVideoClient.videos())
val workManager = WorkManager.getInstance(context) // WorkManager comes from package "androidx.work:work-runtime"

val myVideoFile = File("my-video.mp4")

/**
* You must not call API from the UI/main thread on Android. Dispatch with Thread, Executors,
* Kotlin coroutines or asynchroneous API (such as `createAsync` instead of `create`).
*/
executor.execute {
try {
val video = apiVideoClient.videos().create(VideoCreationPayload().title("my video"))
Log.i("Example", "Video created: $video")
workManager.upload(video.videoId, myVideoFile)
} catch (e: ApiException) {
Log.e("Example", "Exception when calling VideoApi", e)
}
}
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
```
{{/android}}
{{/client}}
{{#uploader}}
{{#android}}
```kotlin
// If you want to upload a video with an upload token (uploadWithUploadToken):
VideosApiStore.initialize()
// if you rather like to use the sandbox environment:
// VideosApiStore.initialize(environment = Environment.SANDBOX)
// If you rather like to upload with your "YOUR_API_KEY" (upload)
// VideosApiStore.initialize("YOUR_API_KEY", Environment.PRODUCTION)
// if you rather like to use the sandbox environment:
// VideosApiStore.initialize("YOU_SANDBOX_API_KEY", Environment.SANDBOX)


val myVideoFile = File("my-video.mp4")

val workManager = WorkManager.getInstance(context) // WorkManager comes from package "androidx.work:work-runtime"
workManager.uploadWithUploadToken("MY_UPLOAD_TOKEN", myVideoFile) // Dispatch the upload with the WorkManager
// if your rather like to use your API key:
// workManager.upload("MY_VIDEO_ID", myVideoFile)
```
{{/android}}
{{/uploader}}

{{#android}}
### Example
Expand All @@ -176,9 +133,9 @@ Examples that demonstrate how to use the API is provided in folder `examples/`.
## Upload methods

To upload a video, you have 3 differents methods:
* `WorkManager`: preferred method: Upload with Android WorkManager API. It supports progress notifications. Directly use, WorkManager extensions. See [example](examples/workmanager) for more details.
* `UploadService`: Upload with an Android Service. It supports progress notifications. You have to extend the `UploadService` and register it in your `AndroidManifest.xml`. See [example](examples/service) for more details.
* Direct call with `ApiClient`: Do not call API from the main thread, otherwise you will get a android.os.NetworkOnMainThreadException. Dispatch API calls with Thread, Executors or Kotlin coroutine to avoid this.
* `WorkManager`: preferred method: Upload with Android WorkManager API. It supports progress notifications, upload in background, queue, network loss,... Directly use, WorkManager extensions. See [example](examples/workmanager) for more details.
* `UploadService`: Upload with an Android Service. It supports progress notifications, upload in background, queue. You have to extend the `UploadService` and register it in your `AndroidManifest.xml`. See [example](examples/service) for more details.
* Direct call with `ApiClient`: Do not call API from the main thread, otherwise you will get an `android.os.NetworkOnMainThreadException`. Dispatch API calls with Thread, Executors or Kotlin coroutine to avoid this.

## Permissions

Expand Down Expand Up @@ -247,23 +204,21 @@ Method | HTTP request | Description
### API key

Most endpoints required to be authenticated using the API key mechanism described in our [documentation](https://docs.api.video/reference#authentication).
The access token generation mechanism is automatically handled by the client. All you have to do is provide an API key when instantiating the {{#client}}`ApiVideoClient`{{/client}}{{^client}}`ApiClient`{{/client}}:
{{^android}}
The access token generation mechanism is automatically handled by the client. All you have to do is provide an API key when instantiating the {{#client}}`ApiVideoClient`{{/client}}{{^client}}`ApiClient`{{/client}}:

```java
ApiVideoClient client = new ApiVideoClient("YOUR_API_KEY");
```
{{/android}}
{{#android}}
{{#client}}
```kotlin
val client = ApiVideoClient("YOUR_API_KEY")
```
{{/client}}
{{#uploader}}
```kotlin
val videosApi = VideosApi("YOUR_API_KEY", Environment.PRODUCTION)
```
{{/uploader}}

On Android, you must NOT store your API key in your application code to prevent your API key from being exposed in your source code.
Only the [Public endpoints](#public-endpoints) can be called without authentication.
In the case, you want to call an endpoint that requires authentication, you will have to use a backend server. See [Security best practices](https://docs.api.video/sdks/security) for more details.
{{/android}}

{{#android}}
{{/android}}

### Public endpoints
Expand Down
53 changes: 11 additions & 42 deletions templates/swift5/README.mustache
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,48 +63,17 @@ Please follow the [installation](#installation) instruction and execute the foll
```swift
import {{projectName}}

{{#client}}
{{projectName}}.apiKey = "YOUR_API_KEY"
// if you rather like to use the sandbox environment:
// {{projectName}}.basePath = Environment.sandbox.rawValue
// If you rather like to use the sandbox environment:
// {{projectName}}.basePath = Environment.sandbox.rawValue

let url = URL(string: "My video.mov")

VideosAPI.create(videoCreationPayload: VideoCreationPayload(title: "my video")) { video, error in
try VideosAPI.uploadWithUploadToken(token: "MY_VIDEO_TOKEN", file: url) { video, error in
if let video = video {
do {
try VideosAPI.upload(videoId: video.videoId,
file: url) { video, error in
if let video = video {
// Manage upload success here
}
if let error = error {
// Manage upload error here
}
}
} catch {
// Manage error on file here
}
// Manage upload with upload token success here
}
if let error = error {
// Manage create error here
}
}{{/client}}{{#uploader}}
// If you rather like to use the sandbox environment:
// {{projectName}}.basePath = Environment.sandbox.rawValue
// If you rather like to upload with your "YOUR_API_KEY" (upload)
// {{projectName}}.apiKey = "YOUR_API_KEY"

try VideosAPI.uploadWithUploadToken(token: "MY_VIDEO_TOKEN", file: url) { video, error in
if let video = video {
// Manage upload with upload token success here
}
if let error = error {
// Manage upload with upload token error here
}
// Manage upload with upload token error here
}
{{/uploader}}

}
```

# Documentation
Expand Down Expand Up @@ -143,14 +112,14 @@ Method | HTTP request | Description
### API key

Most endpoints required to be authenticated using the API key mechanism described in our [documentation](https://docs.api.video/reference#authentication).
The access token generation mechanism is automatically handled by the client. All you have to do is provide an API key:
```swift
{{projectName}}.apiKey = YOUR_API_KEY
```

You must NOT store your API key in your application code to prevent your API key from being exposed in your source code.
Only the [Public endpoints](#public-endpoints) can be called without authentication.
In the case, you want to call an endpoint that requires authentication, you will have to use a backend server. See [Security best practices](https://docs.api.video/sdks/security) for more details.

### Public endpoints

Some endpoints don't require authentication. These one can be called without setting `{{projectName}}.apiKey`:
Some endpoints don't require authentication. These one can be called without setting `{{projectName}}.apiKey`.

## Have you gotten use from this API client?

Expand Down

0 comments on commit 986a786

Please sign in to comment.