From 0aa840873cb26ac0743b78afd8cecf1796914778 Mon Sep 17 00:00:00 2001 From: Stevan Freeborn <65925598+StevanFreeborn@users.noreply.github.com> Date: Tue, 21 Feb 2023 21:12:57 -0600 Subject: [PATCH] docs: update README.md --- README.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3df5d14..06d6c00 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,13 @@ [![NPM](https://img.shields.io/npm/l/onspring-api-sdk)](License.txt) ![npm](https://img.shields.io/npm/v/onspring-api-sdk) -The javascript SDK for the Onspring API is meant to simplify development in Javascript for Onspring customers who want to build integrations with their Onspring instance. +The Javascript SDK for the Onspring API is meant to simplify development in Javascript 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. +**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 as the starting point with the intention of making development of integrations done in Javascript with an Onspring instance quicker and more convenient. +This SDK was developed independently using Onspring's existing [C# SDK](https://github.com/onspring-technologies/onspring-api-sdk), the Onspring API's [swagger page](https://api.onspring.com/swagger/index.html), and [api documentation](https://software.onspring.com/hubfs/Training/Admin%20Guide%20-%20v2%20API.pdf) as the starting point with the intention of making development of integrations done in Javascript with an Onspring instance quicker and more convenient. -## Dependencies +## 🛠️ Dependencies ### Node.js @@ -33,13 +33,13 @@ All methods for the `OnspringClient` make use of the [Axios](https://axios-http. When it is necessary to send requests to the Onspring API using `multi-part/form-data` the [Form-Data](https://www.npmjs.com/package/form-data) package is used. -## Installation +## 💾 Installation Install the SDK using [npm](https://www.npmjs.com/): `npm install onspring-api-sdk` -## API Key +## 🔑 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: @@ -49,7 +49,16 @@ In order to successfully interact with the Onspring Api you will need an API key 4. Click on the **Developer Information** tab. 5. Copy the **X-ApiKey Header** value from this tab. -## Start Coding +**Important:** + +- An API Key must have a status of `Enabled` in order to make authorized requests. +- Each API Key must have an assigned Role. This role controls the permissions for requests made. If the API Key used does not have sufficient permissions the requests made won't be successful. + +### 🔒 Permission Considerations + +You can think of any API Key as another user in your Onspring instance and therefore it is subject to all the same permission considerations as any other user when it comes to its ability to access data in your instance. The API Key you use needs to have all the correct permissions within your instance to access the data requested. Things to think about in this context are `role security`, `content security`, and `field security`. + +## 🧑🏻‍💻 Start Coding ### `OnspringClient` @@ -89,7 +98,7 @@ dotenv.config(); const client = new OnspringClient(process.env.BASE_URL, process.env.API_KEY); ``` -#### Axios Instance Configuration +### `Axios` Instance Configuration By default when you construct an instance of the `OnspringClient` the a new `Axios` instance will also be created. Its `baseURL` property will always be set to the `baseUrl` parameter based to the `OnspringClient`'s constructor and its headers will always contain the proper `x-api-key` header. @@ -120,21 +129,21 @@ Each `OnspringClient` method - aside from `canConnect` - returns an `ApiResponse - `data` - If the request was successful will contain the response data deserialized to custom classes. - `message` - A message that may provide more detail about the request when no successful -## CommonJS or ES Modules +### CommonJS or ES Modules There is support for using either CommonJS or ES Modules depending upon your preference. This documentation will use the later in the usage examples. -## Types +### Types The package is written in typescript and all types are exported and available for you to use. -## Full API Documentation +### 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 as parameters to some of the `OnspringClient` methods. There is also a [swagger page](https://api.onspring.com/swagger/index.html) that you can use for making exploratory requests. -## Examples +## 📋 Examples -Note the following code snippets assume you've already instantiated an `OnspringClient` as shown in the [Start Coding](#start-coding) section. +Note the following code snippets assume you've already instantiated an `OnspringClient` as shown in the [OnspringClient](#onspringclient) section. ### Connectivity