update README.md

2022-05-02 15:34:55 -05:00
parent c4cb7b8733
commit 873170f3e0
1 changed files with 52 additions and 0 deletions
@@ -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.