This week, we released something very near and dear to my heart: the Planning Center API Explorer!
Another Feature From Free Weeks
As a developer, I love working at Planning Center. Nothing is more exciting and fulfilling than utilizing my God-given gifts and interests; but to do that while also supporting other ministry-minded people is a very special opportunity. We are passionate about creating tools that allow you to manage your ministry as effectively and efficiently as possible.
My fellow developers and I are also privileged to work at a place that gives each of us time to work on our own projects that we believe may benefit customers or our internal staff. We call those periods "free weeks". About three times a year, our company takes two full weeks to work on whatever projects we'd like. Yes, you heard that right. Two full weeks.
We've had great free weeks projects over the years—a custom-built arcade cabinet for our office, the internal tool we use to generate the API for our apps, and the Super Pico World game you can play between scheduling volunteers are a few examples.
Does working on stuff like this sound like fun? We are currently hiring developers! Check out https://planning.center/careers/.
Digging Into Your Data
While we have amazing front-facing tools with gorgeous UX/UI that assist you in the day-to-day work of ministry, we also allow the fellow geeks among you to get at just the data through our amazing APIs.
If you are a developer (or just curious about how your data is structured on our servers), you are likely familiar with our API and the great documentation that accompanies it. Every attempt has been made to adhere to the JSON API standard. Because of that, the API itself is structured, standardized, well-documented, and easy to consume. Our documentation also provides examples using curl for interacting with your data.
We also know that not everyone is used to using APIs and the examples provided may not be the easiest things to comprehend. Enter the API Explorer.
Exploring Your Data
During our summer free weeks, I wanted to create something that made it easy for you to discover the data on our server or to learn how to interact with our full-featured app APIs. While full-time developers may have experience building complex URLs to get to exactly the data they want, some others may prefer a UI that exposes all the options—and shows you your own data along the way.
When you first load the API Explorer at api.planningcenteronline.com/explorer, you are greeted with a blank, default state. At this point, the page knows close to nothing about your data or how our API is structured (only that we have four apps that provide APIs—People, Services, Check-Ins, and Giving). When you click on an app, the Explorer hits the API endpoint. Based on the structured data that is returned, it builds out further navigation possibilities. Some of the API endpoints reveal children endpoints where you can drill down deeper into a specific resource's attributes. Most of the endpoints themselves are orderable and queryable and can include associated resources. Each of the options for a particular endpoint are discovered automatically and presented to you to use.
The fact that the explorer is self-discovering means a few important things to you as a developer or a curious inspector:
- It will only return data that you have permission to see. In order to use the API Explorer, you will need be logged in. And since the API knows who you are, it will only return data you are allowed to see from endpoints you are allowed to know about. For example, let's say I'm not an admin for the Check-Ins app. I'm not allowed to see any data there and it returns an error as expected.
- It will always be up to date. Nothing except for the starting points are hard-coded into the Explorer. That means as we add new endpoints or further information to existing ones, it will automatically be discovered by the Explorer without any action required on our (or your) part.
If you are creating an application that consumes the API, you can not only use the Explorer to browse the API graphically but you can also drill down to the exact endpoint you need for your application. There is a box at the top that contains the current URL for the API request which includes any querying, limiting, including, ordering, etc. that you've done. You can simply copy and paste that URL into your application to use it.
The server response is also always available so you can see the raw JSON that the server returns based on your request.
Feel free to play around with the API Explorer. It is read-only at the moment so you can't hurt anything by clicking around aimlessly. I'd like to acknowledge Jesse J. Anderson who helped with the UI of the Explorer and too many Planning Center developers who helped me get it slick enough to release to you.
I truly hope the API Explorer is helpful to you as you find new and creative ways to use the data within our apps.
