The Go SDK for the Onspring API is meant to simplify development in Go 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 Onspring's existing C# SDK, the Onspring API's 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.

Dependencies

Go

Requires use of Go version 1.23 or higher.

Installation

To install the Onspring API Go SDK, use the following command:

go get github.com/StevanFreeborn/onspring-api-sdk-go

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:

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

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

`Client`

The most common way to use the SDK is to create a Client instance and call its methods to interact with the Onspring API. Here is an example of how to create a Client instance. You will need to provide your API key when creating the client. It is best practice to store your API key securely and not hard-code it in your source code.

import "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"

client := onspring.NewClient("your-api-key")

The Client instance can be further configured by providing optional configuration settings via the ClientConfig struct. For example, you can set a custom base URL for the Onspring API if needed:

import "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"

client := onspring.NewClient(
    "your-api-key",
    onspring.WithBaseURL(customURL),
)

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.

Examples

Connectivity

Verify connectivity

import (
  "fmt"
  "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"
)

client := onspring.NewClient("your-api-key")

err := client.Ping.Get(context.TODO())

if err == nil {
  fmt.Println("Connection successful!")
}

Apps

Get App by Id

import (
  "fmt"
  "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"
)

client := onspring.NewClient("your-api-key")

app, err := client.Apps.Get(context.TODO(), 1)

Get Apps by Page

Retrieve a single page

import (
  "fmt"
  "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"
)

client := onspring.NewClient("your-api-key")

page, err := client.Apps.List(t.Context())

Retrieve all pages

import (
  "fmt"
  "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"
)

client := onspring.NewClient("your-api-key")

for app, err := range client.Apps.ListAll(t.Context()) {
  // Do stuff
}

Get Apps by Batch

import (
  "fmt"
  "github.com/StevanFreeborn/onspring-api-sdk-go/onspring"
)

client := onspring.NewClient("your-api-key")

batch, err := client.Apps.GetMany(t.Context(), []int{ 1 })