Python SDK Tutorial Part 1

Tutorial Intro & Setup

So how can a developer integrate with our API? It's very simple! In this tutorial we will walk you through our example python client implementation of our API.

API Request Breakdown

To start with, let's see what an API request looks like; here's an example:

https://api-us.restb.ai/vision/v2/predict?client_key=YOUR_CLIENT_KEY_HERE&model_id=re_roomtype_global_v2&image_url=https://demo.restb.ai/images/demo/demo-1.jpg

What does the above mean? Let's break it down:

1. The URL base:

https://api-us.restb.ai

This is the base URL path for our API service, which is based on the same industry HTTP protocol standard that all websites are built on.

2. The API context:

/vision/v2

This is the context for our API. It contains /vision in the path followed by a version identifier (for now just v2)

3. The API endpoint:

predict

This is the API endpoint which allows the user to use a single Computer Vision solution that Restb.ai has. We'll see how to use multiple solutions at the same time in the future.

4. Parameters:

client_key=YOUR_CLIENT_KEY_HERE
model_id=re_roomtype_global_v2
image_url=https://demo.restb.ai/images/demo/demo-6.jpg

These are the required parameters that are necessary for every API request. They are used as follows:

• client_key - this is required in order to authenticate with our API service
• model_id - this is necessary for specifying which solution is desired
• image_url - this specifies what image to process.

Running our SDK example test suite

In order to better assist developers in integrating with our API, we have provided a fully working example test suite. To run this test suite, please clone this repository and perform the following steps:

1. The first step is to clone our SDK GitHub repository:

git clone https://github.com/restbai/sdk

2. Next, update the run.py file in the restb.examples module with your provided client_key:

client_key = 'YOUR_CLIENT_KEY_HERE'

3. You will need to install dependencies in order to run our SDK. Note that we always recommend using a virtual environment for all deployments:

pip3 install -r requirements.lock

4. To actually run our SDK example test suite, please run the following:

python3 -m restb.examples.run

Implementing a basic, single-threaded client

To start with, notice that we are using python3 for this implementation, so make sure you have a working python3 installation, including pip3, which we will use to install dependencies. Also, if you simply cloned this repository, you can follow along without writing any code; however, it may be beneficial to implement it yourself as you read along. The rest of this tutorial will assume that you will be writing this from scratch.

The package structure is defined below; please create the folders and files as listed:

/
/restb
/restb/__init__.py
/restb/sdk
/restb/sdk/__init__.py
/restb/examples
/restb/examples/__init__.py

Once the above folders and files are created, we are ready to starting writing some code! Let's start by defining some re-usable variables in restb/sdk/__init__.py:

__URL_EU = 'https://api-eu.restb.ai'
__URL_US = 'https://api-us.restb.ai'
__ENDPOINT = '/vision/v2/predict'
__ENDPOINT_MULTIPREDICT = '/vision/v2/multipredict'  # We'll talk more about this later
__MODELS = [
    're_roomtype_global_v2',
    're_exterior_styles',
    're_features_v4',
    're_logo',
    're_compliance_v2',
    're_condition_r1r6_global'
]
__PARAMS = {
    'client_key': None,
    'model_id': None,
    'image_url': None,
    'image_base64': None
}


__all__ = [
    '__URL_EU',
    '__URL_US',
    '__ENDPOINT',
    '__ENDPOINT_MULTIPREDICT',
    '__MODELS',
    '__PARAMS'
]

The URL variables define our two available, region-specific URL bases. You should use the URL base appropriate for your region, or rather, whichever has the lowest latency to your target image server. The two different endpoints have been described as well. We have also provided a dictionary listing of our currently available models. Finally, there is also a list of the required parameters as described above for your convenience.

Once the variables are defined, let's create a simple service callout helper in api.py:

def service(url, endpoint, params):
    return requests.get(url=url+endpoint, params=params, allow_redirects=True, timeout=30)

The above utilizes the requests.py package to send an HTTP request to one of our two API URLs with the specified parameters. There are also two additional parameters specified: allow_redirects=True and timeout=30; these allow for HTTP 301 redirects and sets a client-side timeout of 30 seconds (to prevent I/O caused infinite wait).

To make it easier to manage dependencies, we will need a requirements.txt file. We also recommended freezing dependency versions in a requirements.lock file as good practice.

requirements.txt:

requests

shell:

pip3 install -r requirements.txt
pip3 freeze -r requirements.txt >requirements.lock

Next, we will need to define a function to actually facilitate our test; let's call it test_api:

from restb.sdk import *
from restb.sdk.api import service


def test_api(client_key):

    # note the module variables as defined in restb/sdk/__init__.py
    params = __PARAMS.copy()

    # 1. Pick which API endpoint to use (US vs. EU)
    url = __URL_US

    # 2. Determine which solution (API and model) to use
    model_id = 're_features_v4'  # from list of keys from __MODELS
    endpoint = __ENDPOINT
    params['model_id'] = model_id

    # 3. Insert in your client_key
    params['client_key'] = client_key

    # 4. Pick an image_url
    image_url = 'https://demo.restb.ai/images/demo/demo-1.jpg'
    params['image_url'] = image_url

    # 5. Call the API
    return service(url=url, endpoint=endpoint, params=params)


def run(client_key):
    response = test_api(client_key)
    print(response.text)

This is a pretty simple use case, so let's break it down:

1. First, we pick a URL to test against.
2. Next, we define which solution we want to test by specifying the model_id.
3. We also need to specify our client_key parameter in order to authenticate against our API.
4. Then, we specify what image we want to test with by assigning the image_url parameter.
5. We finish by calling our previously defined service() function as declared in restb/sdk/api.py.
6. Finally, we create a run() method in order to run this test code.

To wrap this all up, we need a restb/examples/run.py script for running all of our tests, including our initial basic test:

from restb.examples import basic


if __name__ == '__main__':
    client_key = 'YOUR_CLIENT_KEY_HERE'
    print('1. running basic example')
    basic.run(client_key)

All that this script does is serve to function as our main executable which runs our previously defined test code. To run this, just execute the following command:

python3 -m restb.examples.run

And that's it! At this point, you have a functional client that can successfully integrate with our API calling a single solution! Navigate onwards to part 2 to learn how to use multiple solutions at the same time with just one API request.