SKYLib•NET Frequently Asked Questions

If you still have questions after reading through the following FAQ, don't hesitate to contact us.

1. What is SKYLib•NET?
2. What Blackbaud data can I access using SKYLib•NET?
3. Can I use SKYLib•NET with multiple Blackbaud products – eg, The Raiser's Edge NXT and The Financial Edge NXT – in the same application?
4. How do I add SKYLib•NET to my application/project?
5. What version of the .NET framework does SKYLib•NET target?
6. Why shouldn't I just write my own SKY API wrapper/library?
7. Will my application stop working/slow down if my SKYLib•NET license expires?
8. Is there a trial period for appraising SKYLib?
9. How often is SKYLib•NET updated?
10. How will I know if/when SKYLib•NET has been updated?
11. How can I set up authorization for my unattended SKYLib•NET application?
12. What happens if my SKY API connection is rate-limited?
13. What is Adaptive Rate-Limit Management (ARLM)?
14. What happens if I run out of daily call quota or there is a Blackbaud server outage?
15. Why can't I can get {XYZ} information from my Blackbaud data using SKYLib•NET?
16. What is "rate-limited" mode?
17. Why is Blackbaud authorization failing?
18. How can I check my API connection prior to doing any "real" work with SKYLib?
19. How is SKYLib licensed?
20. What is my Redirect URI?

What is SKYLib•NET? 

SKYLib•NET is a compiled .NET code library that acts as an intermediary between your own application and Blackbaud's SKY API making is far easier to integrate your application with your Blackbaud data.

So instead of coding low-level HTTP API calls to the SKY API, receiving JSON responses and unpacking them yourself, SKYLib•NET provides you with high-level calls which return .NET code objects.

For example, to get a list of Raiser's Edge NXT Constituents, your own code simply calls Api.Constituent.ListConstituents() and SKYLib will return a fully-formed .NET object of type Constituent.Model.ApiCollectionConstituentRead. (Or, alternatively, List(Of Constituent.Model.ConstituentRead) if you prefer.)

And SKYLib takes care of all of the onerous authorization chores for you as well, popping up the Blackbaud authorization form when required, managing Access and Refresh Tokens, etc.

Lastly, SKYLib•NET is suitable for use in unattended (aka "headless") applications such as Windows and web services.

What Blackbaud data can I access using SKYLib•NET? 

SKYLib•NET supports all SKY APIs and endpoints, including beta releases and previews. So using SKYLib you can access all of the data that the SKY API provides an endpoint for. This includes the following APIs:

Accounts Payable, Church Volunteer, Communication Preference, Constituent, Event, Fundraising, General Ledger, Gift, Gift Batch, List, NXT Data Integration, Opportunity, Payments, School, Statistical Unit, Treasury and Webhook.

And as Blackbaud publishes additional APIs and endpoints SKYLib•NET will support those as well.

SKYLib•NET supports literally hundreds of Blackbaud SKY API endpoints!

Can I use SKYLib•NET with multiple Blackbaud products – eg, The Raiser's Edge NXT and The Financial Edge NXT – in the same application? 

Yes. SKYLib•NET maintains authorization credentials for each API group and automatically swaps between them as required. The only requirement is that your Blackbaud developer account provides access to the API in question in your environment.

The Blackbaud SKY API documentation has more information about this.

How do I add SKYLib•NET to my application/project? 

The demonstration SKYLib•NET Visual Studio solution contains a References folder. In this folder are two files: SKYLib.NET.dll and SKYLib.NET.xml. The first is the actual SKYLib code library, while the second contains all of the in-line documentation and IntelliSense to assist you while creating your application.

When you create your own Visual Studio project/solution, copy the SKYLib files to your project folder and add a reference to SKYLib.NET.

Once the SKYLib reference has been added to your project, you can immediately utilize all of its methods and models within the SKYLib namespace.

Tip: If you make a copy of SKYLib.NET.dll, don't forget to also copy the SKYLib.NET.xml documentation file to the same folder so that IntelliSense is available while you're writing your code.

What version of the .NET framework does SKYLib•NET target? 

SKYLib•NET targets .NET 4.6.2. Your host application therefore must target .NET 4.6.2 or later. Due to internal code constraints, targeting SKYLib•NET to an earlier .NET version is not practicable. This is also the earliest still-supported version of the .NET framework.

Due to Microsoft ceasing support for older .NET versions, it's likely that SKYLib•NET will target later .NET versions as time goes by. But we will always try to target the earliest-supported version of the .NET framework for optimum compatibility.

UPDATE: Microsoft will cease support for .NET version 4.5.2 (as well as 4.6 and 4.6.1) in April, 2022 so SKYLib•NET releases beginning January 1, 2022 now target .NET version 4.6.2.

Why shouldn't I just write my own SKY API wrapper/library? 

Of course, you could. But you'll likely spend more time doing so than is worth the cost of a SKYLib•NET subscription.

We've spent a lot of time developing the SKYLib•NET library, ensuring that the latest SKY API changes and additions are included and that the often-daunting authorization management tasks are taken care of.

And we are committed to keeping SKYLib•NET updated with the very latest changes and additions to Blackbaud's SKY API, with up to weekly releases if necessary.

And with SKYLib, you can take advantage of additional functionality we've added such as the TestConnection methods, call quota and server outage management, call retry options, etc, etc.

All of this means you can concentrate on your own application's functionality in the knowledge that the lower-level code to interact with the SKY API is fully taken care of.

Will my application stop working/slow down if my SKYLib•NET license expires? 

Absolutely not!

An expired SKYLib•NET license only restricts your access to new releases of SKYLib; you're entitled to make unlimited, perpetual use of any version of SKYLib released during your license period.

Of course, we recommend that your keep your SKYLib•NET license current so that you have access to the latest SKY API functionality.

Is there a trial period for appraising SKYLib? 

SKYLib doesn't have a trial version; you can always use SKYLib at a lower API call rate without a license.

Once you've decided that SKYLib•NET is right for you, you simply buy a license to access the fastest API call rate of up to 10 call/s. (See What is "rate-limited" mode? below.)

How often is SKYLib•NET updated? 

SKYLib•NET is updated whenever Blackbaud adds or makes changes to any of its SKY APIs. Generally, new SKYLib versions are issued at the beginning of the week following any SKY API changes.

The SKY API is quite a dynamic beast so we recommend keeping your SKYLib•NET license up-to-date so you're always working with the latest SKY API features.

And because at times Blackbaud releases breaking changes, it is possible that an older version of SKYLib•NET will not functional correctly. SKY API breaking changes are put of our control apart from updating SKYLib to work with them.

How will I know if/when SKYLib•NET has been updated? 

SKYLib•NET has a built-in background function that checks for updates.

Your own code – or a separate utility application – can call SKYLib's CheckVersion method which will communicate with our website's back-end to see if the SKYLib•NET version you are using is the latest. If this method returns True then SKYLib was able to access the version check endpoint. Otherwise the result of the check is False, indicating that SKYLib was unable to perform the check because, for example, an internet connection wasn't available.

If CheckVersion returns True, your code can then make a version comparison between CurrentVersion and LatestVersion and decide what to do, whether it be log the information, pop up a message or send an email to an administrator.

The full (Visual Basic, deskop app) code would look something like this:

 If CheckVersion() AndAlso LatestVersion > CurrentVersion Then
  MessageBox.Show("A new version of SKYLib.NET is available.")
 EndIf

We also send notification emails to subscribers whenever SKYLib•NET is substantially updated.

How can I set up authorization for my unattended SKYLib•NET application? 

There are times when you need to create an application that has no direct human interaction. Examples are Windows Services and other automated, back-end applications.

In these cases, how do you manage SKYLib•NET's initial Blackbaud authorization?

SKYLib is able to operate in "quiet mode", with manual (ie, human) authorization disabled. With quiet mode enabled – by setting the DisableManualAuth flag – if SKYLib is unable to obtain an Access Token for any reason, it will not prompt for user authorization and the Blackbaud sign-in form will not be displayed. SKYLib will simply throw a manageable error on any attempted API call which you can catch and handle appropriately, for example by sending an email to an administrator.

So how does SKYLib perform its initial authorization and obtain Access and Refresh Tokens when used in unattended applications?

In short, in this case, SKYLib doesn't perform an initial authorization at all; a separate application is used to authorize and the resulting settings file information is copied to the unattended application's settings. You can use one of the provided demo applications to perform an initial authorization using the exact authorization credentials your unattended application requires. Then, simply copy the settings file to the machine where the unattended application is installed, eg C:\ProgramData\My Organization\My Application\SKYLib.config.

Note: If you adopt this (recommended) approach you still need to set SKYLib authorization credentials within your application so that SKYLib can perform token exchanges.

This method of pre-authorization "seeds" your unattended SKYLib•NET-based application with initial Access and Refresh Tokens after which they will be automatically exchanged as required by SKYLib, provided, of course, that the Refresh Token is available and valid. At the time of writing, Refresh Tokens are valid for 365 days and Access Tokens for 60 minutes. (A missing, expired or corrupt Access Token will simply result in SKYLib exchanging the Refresh Token for a new token set.)

What happens if my SKY API connection is rate-limited? 

SKY API subscriptions can be rate-limited which means that the Blackbaud server will only accept calls up to a maximum number in a specified time frame, for example, 5 calls/s. Blackbaud does this so that its servers are not overloaded or as prone to DOS (Denial of Service) attacks.

When the call rate is exceeded, the server throws a 429 – Too Many Requests error and provides some information as to how long to wait before resuming API calls.

SKYLib•NET uses our proprietary Adaptive Rate-Limit Management (ARLM) system which tunes the calls to the maximum available rate to avoid the need to retry calls.

The result is that not only does your application never have to handle rate limit errors, your SKY API call quota is not impacted by excessive call retries.

What is Adaptive Rate-Limit Management (ARLM)? 

Adaptive Rate-Limit Management (ARLM) is a proprietary method of tuning the SKY API call rate according to the detected rate limit.

Using Adaptive Rate-Limit Management, SKYLib•NET gradually tunes its call-rate to avoid 429 - Too Many Requests errors, minimizing call retries while allowing the fastest available call through-put.

Adaptive Rate-Limit Management doesn't start working until call-rate errors are detected, so there is no adverse impact on the performance of your application.

What happens if I run out of daily call quota or there is a Blackbaud server outage? 

Blackbaud SKY API subscriptions have a daily call quota – 50-100,000 call/day at the time of writing. Once your daily call quota is exhausted, further calls will fail with the error 403 – Out of call volume quota. Quota will be replenished in 00:06:46.

If this occurs in the middle of your application's processing run it can be catastrophic. A similar problem can occur when Blackbaud's server experiences an outage, for example during maintenance periods.

SKYLib•NET doesn't just pass these errors on to your application; it can handle these events by waiting until it can resume processing, even automatically re-authorizing if the Access Token has expired.

And the way SKYLib manages these events is entirely within your control, from setting call retry parameters, to logging the events, to choosing when or whether to pass exceptions on to your application.

Why can't I can get {XYZ} information from my Blackbaud data using SKYLib•NET? 

Mostly likely, it's because Blackbaud's SKY API doesn't (yet) support the required API endpoint. SKYLib can only access data that is made available by the SKY API.

For example, at the time of writing, it isn't possible to interact with Query data using the SKY API. Likewise, SKYLib•NET is unable to get this information either.

As Blackbaud augments its SKY API, though, SKYLib•NET updates will provide this functionality. So we recommend keeping your SKYLib license current.

What is "rate-limited" mode? 

Instead of providing a trial period for SKYLib, we allow anyone to use it without a license for as long as they like, albeit with a limit on the number of API calls of 1 per second.

So you can use SKYLib to develop and test your applications without the need for a license and then, once you're ready to publish your application or put it into production, you can purchase a SKYLib license to unleash full-speed performance of up to 10 API call/s.

Why is Blackbaud authorization failing? 

The most likely reasons for this are that you either don't yet have a Blackbaud Developer Account or you haven't registered your application in "My Applications".

Once you have a Developer Account, you will be assigned two Subscription Keys which are used in the authorization process.

All applications which connect to Blackbaud's back-end data via the SKY API must be registered. Registered applications are assigned an Application ID and Secret Key which are also used in the authorization process.

Please refer to Blackbaud's SKY API "Getting Started" guide for more detailed information.

Tip: A good test of your credentials is to use one of the SKYLib•NET demonstration projects which are based on "known-good" authorization flows.

How can I check my API connection prior to doing any "real" work with SKYLib? 

Although the SKY API itself doesn't (yet) have any dedicated utility endpoints for testing connectivity, we've added TestConnection endpoints to SKYLib for each API.

To test your connection to an API simply use the associated TestConnection method. For example:

 if (!Api.Gift.TestConnection())
  throw new Exception($"Could not connect to the SKY Gift API: {Api.Gift.TestConnectionMsg}");
 ...

In the background SKYLib makes an economical API call to an endpoint such as GET Constituent/PhoneTypes and simply returns True if the call succeeds and False otherwise, along with a message (TestConnectionMsg). We're hoping that Blackbaud will implement some dedicated utility endpoints in future (whereupon SKYLib will adopt these calls in place of the current proxy calls).

How is SKYLib licensed? 

SKYLib•NET is licensed on an annual subscription basis plus a one-off initial fee. Licenses are tied to your Blackbaud SKY application by the unique Application ID. You only require additional licenses for separately-published applications, not for each individual use of an application. We provide deep discounts for bulk licenses – ask us for a quotation for your needs.

SKYLib can be used unlicensed in rate-limited mode which is limited to 1 API call per second. This is useful during application development or for creating applications which do not require the full call rate of 10 call/s.

Remember: Applications using any version of SKYLib published during your license period will always continue to function at the fastest call rate!

The only exception to this is where Blackbaud subsequently publishes breaking changes to its APIs which prevent previous SKYLib versions from working. Unfortunately, this is beyond our control, but is a good reason to keep your SKYLib subscription up-to-date.

What is my Redirect URI? 

During initial authorization or reauthorization Blackbaud's oAuth2 server provides an Authorization Code (used to retrieve Access and Refresh Tokens) by including it as a query parameter (code) in an HTTP URI such as:

https://protege.com.au/oauth2/callback/?code=7f1d8d4a5ff94710bdf17a7c8a48459a&state=09A671DD.

NOTE: The state query parameter is a random string used to certify that the source of the redirection is from your own application, thus preventing Cross-Site Request Forgery (CSRF) attacks.

Because a potential security risk exists where an attacker could provide a third-party Redirect URI and intercept the Authorization Code, applications registered in My Applications require that Redirect URI(s) be explicitly listed.

Your Redirect URI can be any web location that you have access to, though it is preferred that it is both secure (HTTPS) and within a domain under your control.

More information is available from Blackbaud's site and from the oAuth documentation.

I still have questions

If you still have questions or need help with any aspect of SKYLib•NET, ask us and we'll do our best to help you out.