diff --git a/README.md b/README.md index e69de29..6ab8950 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,52 @@ +# Onspring API Python SDK + +The python SDK for version of the Onspring API is meant to simplify development in Python for Onspring customers who want to build integrations with their Onspring instance. + +## 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 + +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. + +For example: + +```py +import sys +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) +``` + +## Full API Documentation + +You may wish to refer to the full [Onspring API documentation](https://software.onspring.com/hubfs/Training/Admin%20Guide%20-%20v2%20API.pdf) when determining which values to pass 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.