Resource Manager

Overview

The Resource Manager API allows data providers the ability to upload multimedia files to the Intelligent Safety Platform and generate a public URL. These uploaded files are used with the RapidSOS Emergency Data APIs for data provisioning.

Data provisioning is a necessary step to ensure that media files are accessible via the RapidSOS CDN, which is already whitelisted through municipal firewalls, across the Intelligent Safety Platform coverage footprint.

After file upload, the generated URL should be used in any/all other Safety Platform input APIs to reference the uploaded resource. The sample code shown in this document is a useful reference, but in general the flow is as follows:

Get an authentication token
Create an upload/download URL
Upload the resource to the upload URL
Use the download URL in subsequent data provisioning

Audience

This document is intended for developers that are familiar with RESTful APIs, authentication processes (tokens), and API integration. Knowledge of JSON and python programming language can be helpful when reviewing this material.

Note: If you are uploading video for video verification use cases, you may want to follow the requirements defined here. Speak to your RapidSOS contact for clarification.

Making a Request

Step 1: Authentication

The service is authenticated via short-lived OAuth 2.0 access tokens that are valid for 1 hour. API spec found here POST /oauth/token
You must use the “client credentials” grant type for obtaining an access token. These are described as follows:
- Client Credentials Grant Type: Used to authenticate your application’s access to the Multimedia Hosting API.

Step 2: File Upload Endpoint

The main feature of this API is the ability to upload certain file types to RapidSOS managed cloud storage.

Limitations and Best Practices

While there are no restrictions on the file types or file sizes for this service - files will be opened by default in a new tab on a browser at PSAPs.

As general guidance it is recommended that file types be:

PDFs
standard media containers like MP3, MP4, AVI with codecs supported in browsers by default for playback
text files
images like PNGs or JPEGs, etc
It is also strongly recommended to keep file sizes below 10MB.

Please plan to confirm with RapidSOS implementation support for any special use-cases.

Formatting an upload request

This endpoint only accepts POST requests. POST Request to upload a file

When formatting the POST request for the Multimedia Hosting API, you should have already received your bearer token to authenticate your request.
The URL returned by this request is a temporary URL generated by AWS for the purpose of accessing/downloading the uploaded file.
- This URL should be passed through to our Emergency Workflow API so it can be leveraged by RapidSOS Portal and any Partner integrations.

Persistent Uploads: Managing Files

Resolving ref://
When using the persistent_reference mode the URI returned must be resolved to an https:// URL. The reason for this is to support the download of uploaded media via RapidSOS support APIs. GET Resolve resource unique ID into download URL

To receive a “resolved” ref:// just replace {} with the reference URI, something like:

/v1/resources/{ref://xxxx-xxxxx-xxxxx-xxxx}/resolve

This will output if successful:
https://api-sandbox.rapidsos.com/v1/resources/XXXX

Sample Code

NOTE: this example requires the requests python library

import json
import random
import sys
import string
import requests

# API_HOST: target hostname (without https:// prefix or path..)
API_HOST = "api-sandbox.rapidsos.com"

# CREDENTIALS
OAUTH_CLIENT_ID = "XXXXXXXXXXXXXXXXXX"
OAUTH_CLIENT_SECRET = "XXXXXXXXXXXXXXXX"

def main():
    # Step 1: Authentication
    # Authenticate with your RapidSOS client_ID and client_secret
    access_token = authenticate()

    # =======================================================
    # First upload the file and get a url
    # =======================================================

    # Step 2: Request upload
    # Request an upload link to upload for the media file
    data = request_upload(access_token)

    # Step 3: Upload
    # Upload the media file to the requested url
    # Includes required logic to resolve a file URL ONLY when mode = persistent_reference in Step 2
    data_url = upload(data, access_token)

    # =======================================================

def authenticate():
   OAUTH_URL = "https://api-sandbox.rapidsos.com/oauth/token"
   print("Step 1: Authentication\n", f"POST {OAUTH_URL}...", sep="")

   payload = {
       "client_id": OAUTH_CLIENT_ID,
       "client_secret": OAUTH_CLIENT_SECRET,
       "grant_type": "client_credentials"
   }
   response = requests.post(OAUTH_URL, data=payload)
   if response.status_code != 200:
       print(f"Authentication Request failed: status code={response.status_code}")
       print(response.text)
       sys.exit(1)
   data = response.json()
   access_token = data['access_token']
   print('\tAuthentication Successful\n')

   return access_token

def request_upload(access_token):
   url = "https://api-sandbox.rapidsos.com/v1/resources"
   print("Step 2: Request Upload\n", f"POST {url}...", sep="")
   file_name = "test.jpg"
   mime_type = "image/jpg"
   expire = 120
   mode = "temporary_url"
   payload = {
       "file_name": f"{file_name}",
       "mime_type": f"{mime_type}",
       "expire": f'{expire}',
       "mode": f'{mode}'}
   headers = {
       'Content-Type': "application/json",
       'Authorization': f"Bearer {access_token}"
   }
   response = requests.post(url, json=payload, headers=headers)
   if response.status_code != 200:
       print(f"Request failed: status code={response.status_code}")
       print(response.text)
       sys.exit(1)
   data = response.json()
   print("\tUpload Parameters:", payload)
   print(f"\tData URL: {data['uri']}\n")

   return data

def upload(data, access_token):
   upload_url = data["signed_request"]["url"]
   data_url = data["uri"]
   print("Step 3: Upload File\n", f"POST {upload_url}...", sep="")

   fields = data["signed_request"]["fields"]
   files = {"file": open('test.jpg', 'rb')}
   headers = {
       'Content-Type': "application/json",
       'Authorization': f"Bearer {access_token}"
   }
   response = requests.post(url=upload_url, data=fields, files=files)
   if response.status_code not in (204, 200):
       print(f"Request failed: status code={response.status_code}")
       print(response.text)
       sys.exit(1)
   if data_url[:6] == 'ref://':
       url = "https://{}/v1/resources/{}/resolve".format(API_HOST, data['uri'][6:])
       print(url)
       print("Step3: GET {}...".format(url))
       response = requests.get(url=url, headers=headers)
   else:
       print('Resolve reference failed: Invalid scheme you passed am already resolved URL')
       print(data_url)
       print('\tUpload Successful\n')
       sys.exit(1)
   if response.status_code != 200:
       print("Request failed: status code={}".format(response.status_code))
       print(response.text)
       sys.exit(1)
   data = response.json()
   print(data)
   print('\tUpload Successful\n')

   return data_url

# Launch main function
main()