Postman Collection ReadMe File

Janran REST APIs (janrain_postman_collection.zip) is a "Postman collection" of Janrain's REST API endpoints. As you might expect, this collection is designed to be used with the Postman API development environment. If you don't have a copy of Postman, you can download a copy from https://www.getpostman.com.

After you have Postman running, you'll need to import the following two files:

  • Janrain REST API Environment.postman_environment.json
  • Janrain REST APIs.postman_collection.json

To do that, complete the following procedure from within Postman:

  1. In Postman, click Import:
  2. In the Import dialog box, click Choose Files:
  3. Select the two Janrain JSON files and then click Open:

After you import the files two things will happen. First, you should see Janrain REST APIs listed under the Collections tab:

That, as you might have guessed, is your Janrain Postman collection. In addition to the collection, you should also have a Janrain REST API environment. To verify that, click the Environments dropdown list in the upper right corner of the screen; you should see a listing for Janrain REST API Environment:

Go ahead and click Janrain REST Environment to set this as your current Postman environment:

Assuming you did that, that makes this a good time to talk about Postman environments. Postman environments– for our purposes anyway – are simply a collection of variables (and variable values) that can be inserted into a Postman command. In the Janrain REST API environment, you have a number of these variables at your disposal:

And that's great, except for one thing: what are you supposed to dowith these variables? To answer that, let's look at an example. If you're familiar with REST APIs then you know that, at heart, a REST API call is just a URL. For example, a REST API endpoint might have a URL similar to this:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

And yes, in reality it is a little more complicated than "just a URL." Nevertheless, and as long as you have the proper authentication credentials, you can simply paste at least some REST API calls into Postman and get back data. For example, here's a Janrain API call that requires no authentication:

https://greg-stemp.rpxnow.com/api/v2/get_available_providers

Paste the preceding URL into Postman and click Send. You should see something similar to this:

But what does this have to do with Postman environments? Well, like we said, at heart, a REST API is nothing but a URL similar to this:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

But here's what that exact same API call looks like in the Janrain REST API collection:

That definitely does not look like a URL. And what's up with  and?

If you're thinking, "Well, maybe those things have something to do with the Janrain REST API environment," well, you're right: both  and are variables defined within the environment:

In turn, that means that, any time you create an API call using the Janrain REST API environment, you have two ways to do that. For one, you can write out the full URL:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

For the other, you can substitute environment variables for various parts of the URL. For example, we have the environment variable that we can substitute for the base URL (https://v1.api.us.janrain.com) and the environment variable which we can substitute for the application ID (htb8fuhxnf8e38jrzub3c7pfrr). In other words:

/config//clients

And the value of using these environment variables? That's easy. In many of the Janrain API calls, you need to include the application ID; that means that, if you want to, you can memorize your application ID and then type out htb8fuhxnf8e38jrzub3c7pfrr each time you need to use the app ID in an API call. Alternatively, you can just type  each time you need to reference the app ID, and, when it runs the command, Postman will automatically replace the variable name with the value assigned to that variable (htb8fuhxnf8e38jrzub3c7pfrr). It's up to you.

And, by the way, it isup to you: you don't have to use the environment variables if you don't want to. For example, suppose you want to memorize the app ID and type it in yourself. That's fine; here's a Postman example where we've done just that:

This command works just as good as the command that uses .

So then why did we bother to create all these Postman variables if you don't need them? Believe it or not, we did this primarily to make your life easier. When working with the Janrain REST APIs, there's no way to avoid the fact that there isn't one URL that everyone can connect to. For example, this is a valid Janrain API URL:

https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/clients

However, it's valid only if you have the application ID htb8fuhxnf8e38jrzub3c7pfrr. If you don't have that app ID (hint: you don't) then the preceding URL won't work for you. Instead, you need to replace htb8fuhxnf8e38jrzub3c7pfrr with your application ID:

https://v1.api.us.janrain.com/config/gry8fuhxk28h38jrzubfgt1fww/clients

And you'll have to do that for every API call that uses the app ID.

Or here's a thought: you could simply replace the value of the variable with your application ID. To do that:

  1. Click the Environment Quick Look icon:
  2. In the Janrain REST API Environment dropdown list, click Edit:
  3. In the Manage Environments dialog box, replace the Initial Value and the Current Value of the app variable with your application ID, and then click Update:
  4. Click the Close button (X) to close the Manage Environments dialog box.

And what did that gain you? Well, hover your mouse over  and see for yourself:

And there you have it: the {app} variable is now using yourapp ID instead of the default value.

While you're at it, you might want to change the values of the other environment variables as well. And yes, you can add your own environment variables to the Janrain environment. To do that, just bring up the Manage Environments dialog box, scroll to the bottom, and add the new variable:

Note. If you decide to add a new variable, keep in mind that, in the Manage Environments dialog box, variable names do not include the curly braces. That means that variables have names like app_domainand app instead of and .

Here's another thing to keep in mind: environment variables aren't limited just to URLs. Instead, they can be used as parameter values as well. For example:

That could come in handy from time-to-time.

Which reminds us: in addition to updating the environment variables, you should also create a few global variables. (Global variables are similar to environment variables, except that they can be used in anyenvironment. In addition, global variables are not exported when you save an environment.) The Janrain REST API environment uses four global variables;

  • – Found on the Settings page in the Engage Dashboard. Most of the Social APIs require the API Key.
  • – Required if you are working with the Partner APIs. The partner key can be found on the Settings page in the Engage Dashboard. If you don't have a partner key, don't worry about: most people (and most organizations) don't have a partner key.
  • – The client secret of the API client you are using to make your API calls.
  • – The client ID of the API client you are using to make your API calls.

The and variables are especially useful because they are used to configure Basic authentication for each API call:

Again, you can use these two variables, or you can type in your own username (client ID) and password (client secret) each time you make an API call. That's up to you.

To create a global variable, complete the following procedure:

  1. Click the Environment Quick Look icon:
  2. In the Janrain REST API Environmentdropdown list, scroll to the bottom of the list and then, next to the Globals heading, click Edit:
  3. In the Manage Environments dialog box, enter the variable name in the Variable field, then enter the variable value in the Initial Value and Current Value fields:
  4. After you have entered your global variables, click Save, then click the Close button (X) to close the Manage Environments dialog box.

At this point you should be ready to start using the Janrain REST API collection. If you aren't, or if you have any questions about this, drop us a line at education@janrain.com.