How To: Getting Started With Reboot Motion's API

Welcome! If you're new to coding or new to Reboot Motion, you may need some assistance with getting set up so you can properly access the Reboot Motion API. Below you will find some common elements you will see across our tutorials and within our API documentation. If we are missing anything, please let us know at [email protected].

Python Basics & Conventions

Import Statements

Import statements allow us to leverage code from external Python modules and avoid writing repetitive code. If you're interested in learning more about importing Python packages and modules, you can read more about those here.

Below are some of the most common import statements seen in the Reboot Motion API tutorials:

import os

The os module in Python allows the user to interact with the native OS that Python is running on, allowing the user to interact with multiple different Python libraries and functions that are not native to Python itself. This is a great way to use third-party libraries to keep from doing duplicate work. The os module is a module that is provided by Python itself and not a third-party library; that means that you will not need to pip install os in order to use it.

import requests

We also import the requests module (and install it with pip install requests), which is how we are able to send HTTP requests using Python, an essential step to making calls to the Reboot Motion API. We are using the requests module, but there are multiple modules you can use for making HTTP requests in Python and other languages; requests is just the library we’ve chosen to use at Reboot Motion. If your organization uses another library for sending HTTP requests, the functionality will be the same as the requests module and you will want to use that library instead.

If you've never used the requests library before, you can check out the official Python documentation or you can go through this helpful tutorial found on Real Python that walks you through the basics of using the requests library.

import pandas as pd

There are multiple ways to consume and filter CSV files, so you are free to use whichever method you are most comfortable with; but for us, that’s Pandas. Pandas is a third-party library, and must be installed by running pip install pandas. You can find the Pandas documentation here to go more in-depth. Lastly, we import pandas with the alias of pd because that is the industry standard and makes it cleaner and easier to read in the code.

Constants

It’s very easy (and possible) to go through the Reboot Motion tutorials by typing every piece of code out manually and completely, but that can be time consuming and tedious, and allows for a lot of room for error. We recommend using constants that can be reused throughout the code in our tutorial files, allowing you to have more readable code and only have to change the value of a constant in one place instead of multiple. Any constants used in the Reboot Motion tutorials will be defined within the tutorial itself, as they vary.

One caveat to the constants used throughout our tutorials is that they are typically example values. This means you cannot plug and play with the majority of the example values as they currently are; you will need to use the specific values for your organization/player/etc. The example values provided are for a fictional example player.

API Authentication

The primary mechanism for authenticating with the Reboot Motion API is with an OAuth 2.0 Resource Owner Password flow. You can request an access token and refresh token using your Reboot Motion username and password. You will then use the access token to authenticate your requests to the Reboot Motion API. Access tokens expire after 24h, after which point a new one can be requested with the refresh token.

Requesting Access/Refresh Tokens

Make POST request to https://api.rebootmotion.com/oauth/token, passing your Reboot Motion credentials as a JSON payload to retrieve an access token and refresh token.

import requests

access_token_response = requests.post(
    'https://api.rebootmotion.com/oauth/token',
    headers={
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    json={
        'username': '<YOUR USERNAME>',
        'password': '<YOUR PASSWORD>'
    }
)

print(access_token_response.json())

The JSON response will look like this, and the two parameters you'll need to reference are access_token and refresh_token:

{
    "access_token": "<YOUR ACCESS TOKEN>",
    "refresh_token": "<YOUR REFRESH TOKEN>",
    "expires_in": 86400,
}

Refreshing an Access Token

To refresh your access token, simply call the same Token URL (https://api.rebootmotion.com/oauth/token) with a JSON payload containing a refresh_token instead of username and password:

import requests

access_token_response = requests.post(
    'https://api.rebootmotion.com/oauth/token',
    headers={
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    json={
        'refresh_token': '<YOUR REFRESH TOKEN>'
    }
)

You will receive a response identical to the one above, with an updated value for access_token:

{
    "access_token": "<YOUR UPDATED ACCESS TOKEN>",
    "refresh_token": "<YOUR UPDATED REFRESH TOKEN>",
    "expires_in": 86400,
}

Making API Requests with an Access Token Once you have requested or refreshed an Access Token, you can use it to authenticate your requests to the Reboot Motion API. Authentication is performed by passing an API Key as a Bearer Token in the Authorization header alongside your request.

{'Authorization': 'Bearer <YOUR ACCESS TOKEN>'}

For example, to request your player roster from the API, you could use the following code sample:

import requests

response = requests.get(
    "https://api.rebootmotion.com/players",
    headers={"Authorization": "Bearer <YOUR ACCESS TOKEN>"},
    timeout=30
)

print(response.json())

Making a Request to the Reboot Motion API with an Access Token

In order to interact with the Reboot Motion API, you will need to make a request; this will typically either be a GET request or a POST request. You can also make a PATCH or DELETE request, but those are less frequently used. Let's go through what each request type means, before getting to an example:

A GET request is used to retrieve data from the Reboot Motion API. A good example of this is getting a list of players from your organization's roster.

A POST request is used to create a resource by sending data to the Reboot Motion API. A good example of this is creating a new player in your organization's roster.

A PATCH requests is used to update a resource. You would use a PATCH request to update only a portion of the resource (i.e. a player's height).

We do not have many DELETE requests available in the Reboot Motion API, but a DELETE request is used to delete a resource.

Now that we've familiarized ourselves with the possible requests you can send, let's walk through an example showing how to properly make a POST request in your code. These steps will be largely applicable for a GET, PATCH, and DELETE request as well with some minor modifications, which will all be detailed in the Reboot Motion API Documentation.

This example demonstrates how to create a player in your organization with the name John Smith, born on March 30, 1993, who is 6 feet tall, weighs 200 pounds, and hits and throws right-handed.

import requests

new_player = requests.post(
    "https://api.rebootmotion.com/player",
    headers={
        "Authorization": "Bearer <YOUR ACCESS TOKEN>"
    },
    json={
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1993-03-30",
        "attributes": {
            "dom_hand_hitting": "RHA",
            "dom_hand_throwing": "RHA",
            "height_ft": 6.0,
            "weight_lbs": 200
        }
    }
)

Making a Request to the Reboot Motion API with an API Key (Legacy)

In the Reboot Motion tutorials, we will be accessing the API Key from the environment as an environment variable. There are multiple ways to do this; at Reboot Motion, we prefer to use a .env file housed in the root directory of the project. Whichever method you use to store your API Key, you will need to make sure that you are using the correct environment variable name when you make your request and you will want to keep whatever file houses your API Key off of any public GitHub repositories to prevent anyone from gaining access to your organization’s data without your explicit knowledge or consent.

Making a request with an API Key is similar to making a request with an Access Token, except you would pass a different header (X-Api-Key). In Python, the same Create Player request from above would look like:

import requests

new_player = requests.post(
    "https://api.rebootmotion.com/player",
    headers={
        "X-Api-Key": "<YOUR API KEY>",
    },
    json={
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1993-03-30",
        "attributes": {
            "dom_hand_hitting": "RHA",
            "dom_hand_throwing": "RHA",
            "height_ft": 6.0,
            "weight_lbs": 200
        }
    }
)

More Information

Following the above will allow you to make basic requests to the Reboot Motion API. If you are looking to make more complex request, you can find more information in the Reboot Motion API Documentation or some of our other Reboot Motion Tutorials.