Getting started with the Bime API

Follow

(with Marion Pavillet)

You can use the Bime API to create, read, update, and delete resources in Bime. This tutorial shows you how to get started. It provides sample code for completing the following common tasks:

The tutorial focuses on the named user API resource. See About named users below.

Before you start, you'll need an access token to authenticate your API requests. You'll learn how to get one in Get an access token below.

The tutorial uses cURL, a lightweight, command-line tool for making HTTP requests without a web browser. cURL lets you try out various API requests in a command-line interface like the command prompt in Windows or the Terminal on the Mac. You don't need to build a working web application just to try out the API. To install cURL on your system, see Installing and using cURL in the Zendesk Help Center.

Note: Bime provides this article for instructional purposes only. Bime does not support or guarantee the code. Bime also can't provide support for third-party technologies such as cURL and Python. Please post any issue in the comments section below or search for a solution online.

About named users

In Bime, named users are specific people with permission to view or edit one or more dashboards.

Dashboards are shared with named user groups, not with specific named users. To give a named user permission to access a dashboard, the named user must be assigned to a named user group with which the dashboard has been shared.

Once assigned to a group, the user gets permission to access any dashboard shared with the group. Depending on the dashboard's visibility settings, the user might still need to sign in to access it. The options includes Bime, Google, and Salesforce authentication, among others.

See the following topics to learn more:

Get an access token

All Bime API requests must be authenticated with an OAuth token. You typically include the token in an Authorization header in each HTTP request. Example:

curl https://api.bime.io/v3/dashboards \
  -H "Authorization: Bearer ef9809377baa5f80b99fcad6a4f7086e98cab6a4"

where -H specifies a header.

You can get an access token from the Bime user interface for development purposes. However, in a production environment you should implement a more secure OAuth authorization workflow. See Authentication in the developer docs for details.

To get an access token for development purposes

  1. After signing in to Bime, click Admin in the left sidebar, then Manage API in the toolbar on the upper side of the Account Information page:

    image

  2. On the Your Applications page, click New Application.

  3. For Name, enter a brief name for the application, such as "Bime API tutorial".

  4. For Callback URL, enter any valid https URL. It's a required field but since you won't use it in this tutorial, you can enter any URL you like as long as it starts with "https://". Example: https://localhost.

    Your page should look like this:

    image

  5. Click Submit.

  6. Under the Access Token heading, click the Create a new access token link.

  7. Copy and save the token someplace safe. It won't be displayed again.

    image

    Note: Depending on the zoom level of the page, the token might be partially hidden. You can copy it from one of the authentication examples on the page.

    If you lose your token, return to this page to revoke it and create a new one.

Getting Bime resources

In this section, you use the API to list the named users in Bime. The Named Users API documentation lists the following Get Named Users endpoint:

GET /named_users

All Bime endpoints are accessed with https://api.bime.io/v3, so use the following URL to make a GET request for the list of named users:

https://api.bime.io/v3/named_users

You have all the information you need to make an API request with cURL.

Tip: It's a good idea to write and edit cURL commands in text editor before pasting and running them in your command-line tool.

  1. Start by specifying the endpoint and an authorization header:

    curl https://api.bime.io/v3/named_users \
      -H "Authorization: Bearer {access_token}"
    

    Because cURL makes GET requests by default, you don't have to specify GET in the command.

    Note: In Windows, replace the backslash (\) continuation character with a caret (^). Another option is to delete the backslash and line return and paste the command as one continuous line.

  2. Replace {access_token} with your access token. If you don't have one yet, see Get an access token above.

  3. Paste the cURL command in your command-line tool and press Enter.

cURL makes the request and Bime sends a response containing JSON data about your named users. The JSON is one long string. If it's short, you can read it easily enough. Anything more and the data quickly becomes a challenge to read:

image

One solution is to pretty-print the JSON. A Google search returns a number of solutions. The simplest in terms of setup is the "JSON Formatter" extension for Google Chrome. You can get it from Chrome Web Store. After installing it, in Chrome select Windows > Extensions, and select the "Allow access to file URLs" option for the JSON Formatter extension. This enables pretty-printing local files.

Paste your JSON results to a text file and save it with a .txt or .json extension. Then open the file in Chrome (File > Open File).

image

You can see that each user belongs to a named user group specified by the named_user_group_id property.

You can get details about a specific named user group by making a request to the Get Named User Group (singular) endpoint. The endpoint takes a named user group id, as follows:

curl https://api.bime.io/v3/named_user_groups/538492 \
  -H "Authorization: Bearer {access_token}"

The response includes the group name as well as the dashboards that members of the group can access. Example:

image

To learn more about JSON, see Working with JSON in the Zendesk Help Center.

Updating Bime resources

You make PUT requests to update resources in Bime. In this section, you'll update the login email of a named user.

  1. Create a cURL statement that specifies the endpoint, the record to update (the id), the data to use to update that record, the authorization header, and the request method (PUT):

    curl https://api.bime.io/v3/named_users/{id} \
      -d "login=dodger@example.com" \
      -H "Authorization: Bearer {access_token}" \
      -X PUT 
    

    Note: Windows users, remember to replace the backslash (\) continuation characters with carets (^).

  2. Replace {id} with a valid named user id. See Getting data in Bime above to get valid ids.

  3. Replace {access_token} with your access token.

  4. Paste the cURL command in your command-line tool and press Enter.

Bime sends a response containing the updated named user record.

Creating Bime resources

You make POST requests to create resources in Bime. In this section, you'll create a named user.

  1. Create a cURL statement that specifies the endpoint, the data to use to create the record, the authorization header, and the request method (POST):

    curl https://api.bime.io/v3/named_users \
      -d "login=lodger@example.com" \
      -d "named_user_group_id=538492" \
      -H "Authorization: Bearer {access_token}" \
      -X POST
    

    Note: Windows users, remember to replace the backslash (\) continuation characters with carets (^).

    You must assign the new user to a named user group by id (named_user_group_id). You can list all the named user groups and their ids with the Get Named User Groups endpoint.

  2. Replace {access_token} with your access token.

  3. Paste the cURL command in your command-line tool and press Enter.

Bime sends a response containing the new named user record.

Real-world example: Creating authenticated dashboard URLs for your application

The visibility settings of a dashboard might require named users to sign in before they can access the dashboard. For example, if the settings specify Google authentication, then named users have to enter their Google email and password.

This can be a problem if you're building an application and you want users to access Bime dashboards from your application. After signing in to your application, the users would have to sign in again -- possibly with different credentials -- to access a Bime dashboard.

You can use the Bime API in your application to create authenticated dashboard URLs that lets your users access Bime dashboards without signing in. The solution boils down to adding an access token to the dashboard URL. Example:

https://margaritaville.bime.io/dashboard/09CDCFCD1382?access_token=f3045a2291203335

(The 09CDCFCD1382 string identifies the dashboard.)

When the user clicks the personalized link in your application, Bime uses the access token in the url to authenticate and give the user access to the dashboard.

Here's the general application logic using Python and the requests library. Python has the advantage of being easy to follow, but the logic should be the same in your favorite language.

  1. Query your database to get your user's Bime named user id.

    named_user_id = getBimeNamedUserId(uid)
    

    Note: Before implementing this functionality, use the Create Named User endpoint to add your users to Bime as named users in the appropriate named user group. As you create them, save their named user id in your users table.

  2. Make a request to the Get Named User endpoint to retrieve the user's access token:

    url = 'https://api.bime.io/v3/named_users/' + named_user_id
    api_access_token = '36qGEYtphmzBJATTBwMYA3yCnz3tLszg'
    headers = {'Authorization': 'Bearer {}'.format(api_access_token)}
    response = requests.get(url, headers=headers)
    
  3. Grab the user's access token in the response:

    response = response.json()
    user_token = response['result']['access_token']
    
  4. Add the token to the dashboard URL as a query string parameter, then piece together the full url:

    dashboard_url = 'https://margaritaville.bime.io/dashboard/09CDCFCD1382'
    qs = '?' + urlencode({'access_token': user_token})
    href = dashboard_url + qs
    
  5. Display the personalized link in your application:

    <a href="{{href}}" target="_blank">View the data</a>
    

    After the user clicks the link, Bime uses the token in the url's query string to authenticate and give the user access to the dashboard without signing in.

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk