Best Of

As a developer building an app against the Sky API, you're going to have occasions where it will be handy to have tools that can easily generate one-off requests to the API from somewhere other than your app. REST clients are one such tool. This blog post briefly discusses the purpose of a REST client and the benefits of adding it to your toolset.As a member of the team working on Sky API, the time I spend as a consumer of the API often involves testing individual endpoints by verifying responses given certain data scenarios. In this sense, while my goal is to provide a competent API that allows your applications to connect to Blackbaud products, my typical day-to-day use of the API is a little different from the real-world, product-driven use that you and your apps will generate.


However, regardless of your intended usage of the API, you’re going to have instances where the API calls your app is making just aren’t returning the results you want or aren’t performing the resource actions you’d expect. When this happens (and after your trial-and-error app code changes don’t fix the problem), it might be a good idea to take a step back, replicate the scenario in a REST client, and work with the request until you figure out the issue. Working with the request parameters directly from within a client will likely be much easier to do than making a series of code changes based on hunches, so it is helpful to have one of these tools at your disposal.


A common flavor of these tools comes in the form of HTTP or REST-focused clients like Advanced REST Client, Postman, Insomnia REST Client, and Paw, to name a few that Google lists prominently. If you’re a veteran of using REST APIs, you’re probably already familiar with these. If you aren’t, then congrats, this blog post is geared more toward you! This style of client varies in advanced functionality, but at a minimum, they provide a nice user interface for users to define a set of properties by which to construct an HTTP request. This is to say that that these applications provide pretty boxes for you to set the URL, HTTP method, headers, query string parameters, and body of a given request, which you can ultimately execute. The more popular clients, such as those mentioned above, store a history of requests for reference later and facilitate collaboration through exporting collections of archived requests. The better clients also provide for the ability for users to define variables that can be used across multiple requests.


On the SKY API team, although we haven’t officially endorsed the product, we have adopted Postman as our go-to REST client. It satisfies our needs for what a client should do, and sharing a common REST client also allows us to share our archived requests with other team members. This blog post is not intended to teach you how to use Postman, which you can learn more about via the official Postman documentation. Rather, I would like to show how we use this tool on the API team and why using a REST client such as Postman is handy to facilitate exercising API endpoints.


 
Making a call to the API

Fig 1. Example of an API call made using the Postman client



The above screenshot shows a call to the Action (Get) Constituent API endpoint using Postman. To make this call, I need to provide:

• The URL of the request
• The HTTP method (GET)
• The Authorization header using a valid access token
• The bb-api-subscription-key header using the API subscription key from my API developer account.

Once I’ve made the request, I can inspect the response status and body to see if the result is as I expected. I can also choose to save the request parameters for later using the ‘Save’ button next to the blue ‘Send’ button in the screenshot above. When I save this request, I can optionally provide a request description for later reference, and I can add it to a collection of other requests. Even if I don’t explicitly choose to save the request, it still gets stored in my history if I need to recall it later (shown in Fig 2. below).

 
Fig 2. Postman history



The ability to recall and ‘replay’ an old request is an important feature, and it is one that gives the client an advantage over the handy Endpoint Reference ‘Try it’ feature (aka the Developer Console) in the SKY API documentation.  However, the above example by itself doesn’t really show a compelling case for Postman. If you only need a tool to make a single API call, then the SKY API console is great. The added benefit of using a client such as Postman is that it provides functionality that facilitates quickly building additional requests. One of these features is user-defined variables.

Working with user-defined variables

The power of archiving old requests is that you can easily recall these requests and execute it again, or you can use the request as a template by altering parameters to make an entirely different request. One annoying aspect that prevents this from being a quick task for SKY API requests is that if enough time passes after the original call is made, your access tokens expire, or your subscription key gets regenerated, or the latest API version number changes, etc. In other words, if enough time passes, some parameters of your original request are invalid when you attempt to execute the request in the future.


Fortunately, clients such as Postman allow for user-defined variables. By establishing these variables, using them throughout your requests, and updating them when necessary, you’ll be able to run existing and build new requests without the additional copy/paste needed when previous request properties need updating.


 
Fig 3. Action (Get) request using Postman variables



This screenshot shows Postman making the same Action (Get) call using variables that I’ve defined. I have defined variables for the Constituent API base URL, the Authorization header value, and my API subscription key. If the base URL changes for the Constituent API (e.g. the Sky API team updates the latest version number for the Constituent API), my API subscription key is regenerated, or my access token expires, I can easily update my variables and the requests I’m currently working on and my archived requests will use the updated values.

Sharing scripted requests

With all of the requests you’ll be making to the API, it’s nice being able to organize archived requests for easy reference later. Many clients let you do just that (Postman calls these organized sets Collections). It’s also nice being able to share those collections with others to save them from having to build these requests themselves or to demonstrate different behaviors of the API. A good client will let you do that too.


On the SKY API team, we export and share collections to facilitate testing, demonstrate different API behaviors, or just to save each other the time it takes to construct our own requests for a given set of endpoints (e.g. CRUD endpoints around Actions, Address, Email Address, etc… from the Constituent API). While we on the SKY API team are experts on calling our own API, we are individuals working on separate API endpoints (or different aspects of the API infrastructure altogether), so even we keep a repository of these Postman collections. It may help your teams to collaborate as well.

In Conclusion

I’ve covered just a few cases for why a REST client is an important tool for us. However, I hope I’ve conveyed a bit of what for how it might help you and your teams. There are many additional features I didn’t covered such as: Environment-based user-defined variables (especially important to an API team exercising endpoints in multiple states of the development lifecycle); building integration test suites (also pretty applicable to an API team); and even cloud storage to facilitate in the sharing of collections. However, even with their core functionality, REST clients are excellent tools and definitely ones you’ll want to consider if you plan on working with REST APIs.