Sending Your First API Request

Requirements

To make requests to the OnSite API, you’ll need:

  • The App ID and Private ID of the application. If you have a demo version of OnSite, you can use the App ID com.lightspeed.onsite.demo and any string as the Private ID. If you are using a paid version of OnSite, then you must first register using the steps in Registering Your Application. That page also tells you how to retrieve the App ID and Private ID that you’ll need.
  • The username and password of a user on your OnSite installation. On a demo version, the username if left unchanged is lightspeed and the password is admin.
  • A hostname or IP address that will connect to your OnSite Server.
  • The port the OnSite Server is using. The default port is 9630.

Sending the Request

To connect to the OnSite API, we must pass the User-Agent and X-PAPPID of our application to the authorized Lightspeed server with a valid Lightspeed username and password. The User-Agent is the App ID with a version, while the X-PAPPID is the Private ID for the application. In the example below, the username is lightspeed and the password is admin.

# Request
$ curl -k \
--header 'X-PAPPID: 12345678-90ab-cdef-1234-567890abcdef' \
--header 'User-Agent: com.lightspeed.onsite.demo/1.0' \
--user 'lightspeed:admin' \
'https://localhost:9630/api/'

# Response
<resources/>

Congratulations! You made your first request to the API.

Sending the Request with Python

With a bit more set-up, that first request can also be accomplished using a script. The language of choice in this example, and the tutorials, is Python.

Setup the Project Directory

Before writing code, the project has to be setup. These steps assume that python (2.7) and pip are installed on the system and accessible through the terminal.

Run the following commands in the terminal:

# Create a project directory.
mkdir demo_app && cd demo_app

# Install virtualenv on the system, if it is not already.
# Only need to do this once.
sudo pip install virtualenv

# Setup the virtualenv.
virtualenv venv
source venv/bin/activate

# Download dependencies.
pip install requests

Writing the Python Script

After this is done, create the following first_request.py file in the demo_app directory. The file will contain the following:

"""
The simplest request that can be made to the OnSite API. Prints the response.
"""
import requests

# Customize these to your install.
ONSITE_HOST = 'localhost'
ONSITE_PORT = 9630
ONSITE_USERNAME = 'lightspeed'
ONSITE_PASSWORD = 'admin'
APP_ID = 'com.lightspeed.onsite.demo'
APP_VERSION = '1.0'
APP_PRIVATE_ID = '12345678-90ab-cdef-1234-567890abcdef'

# Send request to the API.
response = requests.get(
    'https://%s:%d/api/' % (ONSITE_HOST, ONSITE_PORT),
    auth=(ONSITE_USERNAME, ONSITE_PASSWORD),
    headers={
        'user-agent': '%s/%s' % (APP_ID, APP_VERSION),
        'x-pappid': APP_PRIVATE_ID},
    verify=False)

# Display the response from the API.
print(response.text)

You can now execute the script from the terminal:

# Execute the code.
python first_request.py

# Output
<?xml version='1.0' encoding='UTF-8'?>
<resources/>