onspring-api-sdk-python/README.md

Onspring API Python SDK

The python SDK for version 2 of the Onspring API is meant to simplify development in Python for Onspring customers who want to build integrations with their Onspring instance.

Note: This is an unofficial SDK for the Onspring API. It was not built in consultation with Onspring Technologies LLC or a member of their development team.

This SDK was developed independently using their existing C# SDK, their swagger page, and api documentation with the intention of making development of integrations done in Python with an Onspring instance quicker and more convenient.

Dependencies

Python

Requires use of Python 3.6.0 or later.

Requests

All methods for the OnspringClient make use of the Requests library to interact with the endpoints of version 2 of the Onspring API.

Installation

Install the SDK using pip:

pip install onspring-api-sdk-python

API Key

In order to successfully interact with the Onspring Api you will need an API key. API keys are obtained by an Onspring user with permissions to at least Read API Keys for your instance via the following steps:

1. Login to the Onspring instance.
2. Navigate to Administration > Security > API Keys
3. On the list page, add a new API Key - this will require Create permissions - or click an existing API key to view its details.
4. Click on the Developer Information tab.
5. Copy the X-ApiKey Header value from this tab.

Start Coding

OnspringClient

The most common way to use the SDK is to create an OnspringClient instance and call its methods. Its constructor requires two parameters:

• baseUrl - currently this should always be: https://api.onspring.com
• apiKey - the value obtained by following the steps in the API Key section

It is best practice to read these values in from a configuration file for both flexibility and security purposes.

Example config.ini file:

[prod]
key = 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000
url = https://api.onspring.com

Example constructing OnspringClient:

from OnspringClient import OnspringClient
from configparser import ConfigParser

cfg = ConfigParser()
cfg.read('config.ini')

key = cfg['prod']['key']
url = cfg['prod']['url']

client = OnspringClient(url, key)

ApiResponse

Each OnspringClient method - aside from CanConnect - returns an ApiResponse object which will have the following properties:

• statusCode - The http status code of the response.
• data - If the request was successful will contain the response data deserialized to custom python objects.
• message - A message that may provide more detail about the requests success or failure.
• raw - Exposes the raw response object of the request if you'd like to handle it directly.

The goal with this ApiResponse object is to provide the flexibility to do with the response what you'd like as well as already having the raw JSON response deserialized to python objects.

If you do want to handle and/or manipulate the response object yourself you will want to use the value of the ApiResponse's raw property which will be a Response object from the Requests library.

Full API Documentation

You may wish to refer to the full Onspring API documentation when determining which values to pass as parameters to some of the OnspringClient methods. There is also a swagger page that you can use for making exploratory requests.

Example Code

The examples that follow assume you have created an OnspringClient as described in the Start Coding section.

Verify connectivity

canConnect = client.CanConnect()

if canConnect:
    print('Connected successfully')
else:
    print('Attempt to connect failed')

Get Apps

Returns a paged collection of apps and/or surveys that can be paged through. By default the page size is 50 and page number is 1.

response = client.GetApps()
  
print(f'Status Code: {response.statusCode}')
print(f'Page Size: {response.data.pageSize}')
print(f'Page Number: {response.data.pageNumber}')
print(f'Total Pages: {response.data.totalPages}')
print(f'Total Records: {response.data.totalRecords}')

for app in response.data.apps:
    print(f'Id: {app.id}')
    print(f'Name: {app.name}')
    print(f'href: {app.href}')

You can set your own page size and page number (max is 1,000) as well.

pagingRequest = PagingRequest(1, 100)
response = client.GetApps(pagingRequest)
  
print(f'Status Code: {response.statusCode}')
print(f'Page Size: {response.data.pageSize}')
print(f'Page Number: {response.data.pageNumber}')
print(f'Total Pages: {response.data.totalPages}')
print(f'Total Records: {response.data.totalRecords}')

for app in response.data.apps:
    print(f'Id: {app.id}')
    print(f'Name: {app.name}')
    print(f'href: {app.href}')

Get App By Id

response = client.GetAppById(appId)

    print(f'Status Code: {response.statusCode}')
    print(f'id: {response.data.app.id}')
    print(f'Name: {response.data.app.name}')
    print(f'href: {response.data.app.href}')

Get Apps By Ids

Get Field By Id

Get Fields By Ids

Get Fields By App Id

Get File Info By Id

Delete File By Id

Get File By Id

Save File

Add Or Update List Value

Delete List Value

Get Records By App Id

Get Record By Id

Delete Record By Id

Get Records By Ids

Query Records

Add or Update A Record

Delete Records By Ids

Get Report By Id

Get Reports By App Id