API Integration Part 1: ProcFu and OAuth 2

📖

Contributed by Andrew Cranston, CTO of We Are Gamechangers.

A huge thank you to Andreas for letting me post on his blog, and I’m very excited to share some information that may break open a whole new world for Podio developers, even those who are just starting out. I realize this post may seem long and daunting, but if you’re interested in developing the skills necessary to write your own API integrations, I ask you to stick with me. It’s easier than you think.

First, a short love letter. If you are developing in Podio and GlobiFlow, and you’re not yet using ProcFu, you’re seriously missing out. ProcFu is a tool that provides “middleware” scripts that you can send HTTP requests to using the Remote POST/GET action in GlobiFlow, or even using cURL from your own servers. These scripts are intensely useful and can remove the necessity to build complicated, multi-action flows to perform what could otherwise be a simple procedure. ProcFu has already saved me a lot of time and headaches and quickly become one of the sharpest tools on my belt.

Not all of the scripts are directly related to Podio/GlobiFlow either; some have value in many other programming efforts, such as sending a cURL request, finding a value in a JSON object, or setting variables to be called upon later from anywhere.

But the reason I’m blogging today is to draw attention to what I feel is ProcFu’s biggest draw, related to both inside P/GF and out, and that is the API Service functions.

What's an API?

If you do any developing at all, you’re most likely familiar with what an API is but let me try to clarify for all. API stands for application programming interface. Software systems offer them up as a way of interacting with the system from outside. GlobiFlow, for example, is software that’s built directly on top of the Podio API, so when you create or update items in GF, it sends the requests to Podio via the API on your behalf. Podio’s extensive API is one of its strongest advantages, and GlobiFlow’s mastery of that API is why we all depend on it every day, because it gives us the power that we would otherwise have to code for ourselves.

That being said, understanding the language of APIs and how these requests are sent and received is not difficult. The most popular APIs on the web can send and receive requests in different languages, but JSON is by far the most popular, the easiest to understand and manipulate (and the one Podio uses), and JSON will be my focus for the rest of this post.

An Introduction to JSON and Methods

JSON (JavaScript Object Notation) is a simple format that emphasizes readability. You build the object with a “key” (the “thing” you want to add/change) and then give it a “value”. You then send your formatted JSON object to the server using one of these five methods, depending on why you’re sending it.

POST - normally used to “create” information

GET - normally used to “read” information

PUT and PATCH - normally used to “update” information

DELETE - normally used to “delete” information

By sending a JSON object and a method to the server, you’re telling it what you want to do. The good news is that not only is the act of building JSON objects in GlobiFlow SUPER easy, sending them via ProcFu is even easier.

I’m going to use the GoToMeeting API as my example, as this is a super easy solution to build and you might consider building this versus the built in Podio integration, as it saves a couple of clicks and gives you the URL in a place where you can email it out if you want.

Take a look at the GoToMeeting API Reference and scroll down to the section about meetings. You will see what actions are available via the API. We will focus for now on the operation to send a POST to create a meeting.

If you click this option, you will see the parameters required in your request, and what response you can expect to receive (some requests may not be successful; formatting is very important as well as authentication, which we’ll cover later).

The JSON object I must send to create a meeting is shown below.

{
  "subject": "string",
  "starttime": "2018-02-02T17:00:00Z",
  "endtime": "2018-02-02T18:00:00Z",
  "passwordrequired": true,
  "conferencecallinfo": "string",
  "timezonekey": "string",
  "meetingtype": "immediate"
}

Two curly brackets, containing a set of keys and values. Some keys might require arrays as their value, but for now we’ll keep it simple. You can read for yourself in the documentation what each of these keys mean, and most API docs will be very clear on how each value should be formatted to ensure success.

To create a JSON object in GlobiFlow, create a custom variable and use the json_encode function like this.

This will produce a JSON object that you can then send in a POST request. Before we can do that, we need to address authentication, and this is where ProcFu comes to the rescue.

Authentication and OAuth 2.0

Obviously, we wouldn’t want just anyone making API calls on our behalf without our consent. We need to authenticate ourselves with the API with every request. Most modern APIs handle authentication through the OAuth 2.0 protocol, which can be a bit confusing to explain, but let me give it a try.

You register an application and receive a set of codes, the client ID and the client secret.

You send a request to exchange these codes for an authorization code, which must be sent to a specific script (via a supplied redirect URI) that you would otherwise have no choice but to code yourself.

This script sends the authorization code back immediately and receives an access token. This token will be used to authenticate that user for all of your API calls.

This access token normally expires after a short period of time, in which case you need to use a provided refresh token to gain another access token.

This is the part of API work that can make newbies go cross-eyed. There have been efforts by many in the GlobiFlow community to try and make this process more user friendly to and make it easier to gain a good access token (because once you have one, the rest of the process is a dream), but nothing has yet even come close to ProcFu in terms of ease.

ProcFu will remove all the work necessary to deal with access tokens, and simply let you create “users” within your own API framework, and then make calls on behalf of those users. First, we must set up an API Service in ProcFu. Log in, click Acct in the top right hand corner and click Add API under API Services.

Let’s go through the basic requirements:

Client ID and Client Secret - When you sign up for developer access to an API, you will receive these codes. For example, in Podio, you can find them in Account Settings => API Keys. You must supply a redirect URI (the URL that receives the code between steps 2 and 3 above), and for ProcFu, this will always be simply procfu.com. Easy-peasy.

Authorize URL and Access Token URL - The API documentation will normally have a section related to authentication, and will indicate what these URLs are. You can see the Podio URLs listed there as examples. Here are my values for the GoToMeeting API.

The rest of the options are straight forward (except for scopes, which some APIs use to provide different access types) but this is the bare minimum we need to get started.

Always keep your Client ID and Client Secret private, otherwise people could make API requests on your behalf!

Your First ProcFu Call - Login Link

First things first, if you’re planning on using ProcFu (and you’re obviously interested), you really should download the free Chrome Extension. You’ll see in my screenshots going forward that ProcFu becomes a new action in GlobiFlow, and a lot of information is filled in automatically. Once you install the extension, you just furnish it with your ProcFu access token (found on your Acct page, which you should also keep secret!) and this is also handy if you’re managing multiple ProcFu accounts.

Once you have created an API Service, you can create “users” inside your own API framework in ProcFu. You can use whatever values for the user IDs that you want (Podio Item IDs, custom IDs, email addresses, it doesn’t matter) and then when you make an API call on behalf of that user, you use their ID to authenticate as that user. You may want to use Podio to store these values somewhere so you can call upon them when you need them (and if you’ve read this far, you can probably figure that bit out on your own).

The first script we’re going to use allows us to get a login link that we can send to the user to authenticate their account. In GlobiFlow, select ProcFu, select the script for Get Login Link, and you will see a new action with the correct URL already filled in and some dummy parameters to alter.

You can see the two parameters necessary are which service you’re using and what the ID for the user will be. Supply both of these and when the flow runs, the variable procfu will return a URL. If we simulate variables, we can see this URL.

When the user clicks on this link, they will be directed to the application and asked to grant access. Once they do, you are then free to use the second ProcFu link to make an API request with their user ID.

Your Second ProcFu Call - Making an API Request

Once the user has authenticated, we use the second script to send a request on their behalf.

You already know the API service and the user ID. The Request URL and the method would be found in the API documentation (for example, to create a meeting in GoToMeeting, you send a POST request to https://api.getgo.com/meetings). We need to format a JSON object to send the information necessary. You can read the documentation for yourself, it has a clear description of what each key is for and how to format your value.

You can see my fully formatted request above. Now, if we look at the API documentation, we can see the JSON object we expect to receive as a response.

[
  {
    "joinURL": "string",
    "meetingid": 0,
    "maxParticipants": 0,
    "uniqueMeetingId": 0,
    "conferenceCallInfo": "string"
  }
]

The joinURL value is what we’re really after. This is the meeting link that we can store in Podio or send to other contacts. In order to sift through the entire JSON response for the one value we really want, we can use ProcFu’s Find in JSON to supply a key and return the value.

You’re now holding a variable in GlobiFlow called URL that contains the meeting link, and you’re free to continue based on what you want to do with it.

Conclusion

It would be impossible to write a blog post describing every obstacle you’ll cross when writing API integrations. Some JSON objects are very complex and require careful parsing to get what you need (made easier now by the recent addition of using “For Each” in GlobiFlow to sift through an array of objects returned from a Remote POST or ProcFu action) but hopefully, you’ll take away three things from reading this post:

ProcFu can make your life as a Podio developer so much easier and you should check out what other scripts are available to help you do your work.

API integration (using RESTful APIs based on JSON) is easier than most people realize.

One of the biggest barriers of API integrations is figuring out the OAuth 2.0 puzzle, and ProcFu does this for you with no fuss whatsoever.

Thank you for reading and happy exploring! Come share your discoveries with the entire GlobiFlow community!