API & Webhooks

Getting Started: Building Out Your Toolbox [Part 1 of 2]

  • 21 September 2022
  • 10 replies
  • 2029 views

Userlevel 7
Badge +3

This guide is the second in a series of new guides brought to you by @Bfarkas. Links to the full Guide Series can be found at the end of this article.

 

Welcome back!

 

If you haven’t already, I encourage you to read the official kick off guide for this new series to get some insight into my goals, method, and thinking when approaching this guide series as a whole.

 

Alright, let’s begin with Part 1.

 

TextDescription automatically generated

 

Before setting out on any type of journey, we must do a little prep work. Without it, we simply won’t get very far. When it comes to the work we will be doing, this prep has to do with understanding how the Docebo API works, setting up a few tools so we can easily interact with it, and organizing ourselves to keep track of our work. In this type of work, the more tools at your disposal, the better.

 

 

In this guide, we will be covering the following:

  • The Docebo API Browser: What is it? How to use it? When to use it?

  • Postman: A free desktop application that lets you easily explore the API.

  • Power Automate: If you have Office 365, let’s talk about building a custom Docebo connector to let you quickly build powerful workflows.

  • API Usage Monitoring: There are restrictions when working with an API. Let’s cover a few techniques on how to manage those.

 

Guide Table of Contents

 

The Docebo API Browser

 

Overview

I will not be going into heavy duty API documentation, as Docebo’s help section already does a great job at that. Here are some useful links that I suggest reading through or at least being familiar with while doing this type of work:

 

Once you are all set up to work, one of the best resources at your disposal is the API Browser. This is the definitive source of which API endpoints are available and how to use them. Additionally, it lets you try them out right from within your browser. This is great for testing, doing a quick call to get a piece of information, or researching which endpoint will be best to use for a purpose.

 

Access and Navigate the API Browser

To access your API Browser, simply open a web browser and navigate to: https://<[yoursubdomain].docebosaas.com>/api-browser/

 

You should be brought to a page that looks similar to the image below:


Graphical user interface, text, applicationDescription automatically generated

 

Now, let’s orient ourselves to the page:

 

Services Menu

Use this to switch to the right area of APIs you are looking to use. Most commonly, you will use learn and manage.

 

It may not be obvious where the endpoint you're looking for is located. The best way to get your bearings is to take a look around!

Token If you have already gotten an authentication token from some other method, paste it here and it will be used to authenticate and use the endpoints within the browser. I do not typically use this. An easier way to do this inside the browser will be covered later, but it does come in handy to be able to test tokens this way.
API Reference

List of endpoints categorized. Scroll through this list to find what you are looking for.

 

Remember this page is just a webpage. You can use ctrl/cmd + f and then search for words on the page if you are not sure where the endpoint might be.

Endpoint Information Pane When you select an endpoint, information about it will be displayed here. This includes which type it is, the URL, and fields that require data for the endpoint to work.
Try Button

If you fill in all the required fields, and have a proper authentication token loaded, you can click this button to actually run the API.

 

WARNING: Be careful, this is not a test or example, it will actually run the API. In general, I tell people to stick with only the ‘GET’ types until they are comfortable with them (as you can’t break anything).

OAUTH Button

This lets you log into your instance of Docebo and authenticate for a valid authentication token. Do this before you use the Try button. This should load the token automatically into the Token field in the top left.

 

You must be a Superadmin in Docebo in order to interact with the API at this time. (There is an exception to this using embed codes, but we’ll cover that later in a different article.)

Response Sample Pane This gives a sample payload schema of what to expect from successful use of the endpoint. This comes in handy when designing things and for knowing what information will be provided to you.

 

 

Example: Using the API Browser to Get User Information

Ok, now that you know how to access the API Browser and understand how to move around it, let’s have some fun and use the API!

 

Let’s walk through a simple but useful example; I want to look up a specific user’s information

 

First, I navigate to the API Browser, and look for an appropriate endpoint. In this case, I see there is a ‘User’ category under the ‘manage’ service. Scrolling down, I see several choices close to what I am looking for: 

  • Return list of users: I could probably use this. A list of one is still a list right? Let’s keep looking though.

  • Create user: I don’t want to make a new user; I want to look at an existing user. Not right.

  • View a user’s info: PERFECT! This is what I want.

Graphical user interface, applicationDescription automatically generated

 

Now that I have selected ‘View a user’s info’, the information related to it has loaded into the middle. The only required information is the user’s ID. Alright, I need to look that up. This is the unique Docebo User ID. I can get this from reports, or by doing a CSV export from the user management area (for more on finding IDs for items around the system, check out this great community article.)

 

Once I have found the user ID, I can load it into the required field.


Graphical user interface, text, applicationDescription automatically generated

 

Ready? Here’s the fun part. Make sure you have a valid token loaded and click the Try button!

Graphical user interface, text, applicationDescription automatically generated

 

💥 BAM! I got a successful call, and here is all the information about the user I was curious about. You can see how great this can be to find some quick information, an ID, or the like that may not be available to you from the front end interface of Docebo.

 

Let’s take it a step further. Say I don’t know the exact user. Let’s return to the ‘Return a list of users’ endpoint. Upon selecting it, you may notice that there are far more options available to fill in compared to our previous example. That is because this endpoint has no required parameters. You can just run it empty and simply get a list of all users set to the default settings. Let’s try an edited one though.

 

I want to find all of my test accounts. To do this, I can simply go to the ‘search_text’ parameter and enter ‘test’ since I use that for all their last names.


Graphical user interface, text, applicationDescription automatically generated

 

Now, I only want standard test users, no Superadmins or Power Users, so I scroll down and find a parameter that does just that and simply put a 1 in it.

 

Graphical user interface, text, application, emailDescription automatically generated

 

Just for fun, let’s order the list. Set the ‘sort_attr’ to ‘last_name’ and ‘sort_dir’ to ‘asc’, and you’ll have a nice, alphabetical list.

Graphical user interface, text, application, emailDescription automatically generated

 

Hit that Try button again.


Graphical user interface, text, applicationDescription automatically generated

 

And just like that, I have the list of users I need and all their information for use. That wasn’t so bad, right? Try out a few more simple requests (stick to the ‘GET’ requests for a while to be safe), and you are on your way to being an API pro in no time!

 

 

Postman: Like the API Browser but with Memory!

Now that you are able to have some fun using the API browser, you might find the joy of it working quickly fades… What once was a mystery is now second nature, and you begin to get frustrated by its limitations. I am going to bet the first frustration you will have is that there are certain calls you like to use over and over, and it gets annoying to fill in all the fields the same way each time, as the API browser does not remember what you did last time. 

 

Good news! We can easily solve this frustration. Enter Postman.

 

 

Install Postman

Postman is a great tool to have at your disposal when beginning to do API work. It allows you to set up and interact with various application’s APIs. Your work will be saved, and it allows you to easily duplicate and modify individual calls. It is incredibly powerful. I will show you how to set it up to work with the Docebo API similarly to the API Browser, but I want to emphasize there is a ton more you can do here. If curious, go check out YouTube for some great tutorials.

 

You can download the latest version of Postman for your computer here: https://www.postman.com/downloads/ 

 

While on the website, I encourage you to sign up for a free account. The benefit of this is that you can sync your work to this account and between computers, allowing you to move computers without needing to start over from scratch.

 

 

Setup OAUTH 2.0 App in Docebo

In order to use the Docebo API, you need to create and configure an OAUTH 2.0 app within the API admin area.

  1. Log in and select the Admin Menu (Gear icon top right corner).
  1. Select ‘Manage’ under the ‘API and SSO’ area.

Graphical user interface, text, applicationDescription automatically generated

 

  1. Select ‘API Credentials’.
  1. Select ‘Add OAuth2 App’.

Graphical user interface, text, applicationDescription automatically generated

  1. Fill in the required information:
  • App Name: Give the app a distinctive and descriptive name so you can differentiate it from others.
  • App Description: Important to detail the purpose of the app so that other admins are clear what each is for.
  • Client ID: Think of this like a username. Make it unique and make sense for the account.
  • Client Secret: This will be generated automatically, and you can think of it like the account’s password. You will need it later, so make a note of this, but protect it.
  • Redirect URL: Each application you use will have a unique one of these. It tells the applications how to talk to each other. For Postman, use this: https://www.getpostman.com/oauth2/callback
  • Select ‘Show advanced settings’ check box and make sure the ‘Authorization code + implicit Grant’ checkbox is selected. (Yes, you can use other types, but this is the route I recommend for beginners to stay safe.)
  1. Select ‘Confirm’.

 

 

Configure Postman for Authentication with Docebo

Ok, now that you have Postman installed and a Docebo OAuth2 app configured, let’s create a new workspace and set it up to authenticate properly with Docebo to use the API.

 

  1. Open Postman
  1. If it is your first time, you should be prompted for what you wish to do. Select the ‘Collection’ option. If this window does not open for you, look for the ‘New’ button and select ‘Collection’.

Graphical user interface, applicationDescription automatically generated

 

  1. Name the Collection something distinctive and descriptive. Feel free to give it a description.
  1. Select the ‘Authorization’ tab
  1. Under type, switch to ‘OAuth 2.0’

Graphical user interface, text, application, emailDescription automatically generated

 

  1. Select the ‘Get New Access Token’ button to launch the configuration panel, then configure the following:
  • Token Name: If you are using multiple systems/applications/integrations, you may wish to give this a descriptive name. You will see them all together in the token management window. Even if only using Docebo, you still might want to keep sandbox vs. production named differently.
  • Grant Type: Implicit
  • Callback URL: https://www.getpostman.com/oauth2/callback
  • Auth URL: https://<[yoursubdomain].docebosaas.com>/oauth2/authorize
  • Client ID: Enter the value you created when setting up the Oauth 2.0 App in Docebo
  • Scope: api

Graphical user interface, application, email, websiteDescription automatically generated

 

  1. Select ‘Request Token’.
  1. You should have a pop-up window asking you to authorize. Use your Docebo username and password to get through this window.

If you have SSO enabled, you need to use the local username and password for Docebo, which may not be your SSO username and password.

  1. You should see the ‘Manage Access Tokens’ screen giving you the information about your new token.

Graphical user interface, applicationDescription automatically generated

 

  1. Select the ‘Use Token’ button.

Please note: the token is only good for one hour. At that time, you will need to return to the Auth tab of the collection and generate a new token.

 

Now you are all set for some fun!

 

 

Build a Docebo Request

Now that we have configured how to authenticate to Docebo, let’s build out some requests. The easiest way to follow this is through an example, so let’s redo the same two calls we did in the API Browser section. First up, look up information about a user:

 

  1. Select ‘Request’ from the new menu.
  1. Give it a distinctive and descriptive name. In this case, I’ve titled it ‘Get Information About a User’.
  1. Make sure the collection you just made is selected (or if you have multiple collections, that the right one is picked).

Graphical user interface, text, application, emailDescription automatically generated

 

  1. Select ‘Save’.
  1. The type will default to ‘GET’ which is what we need, but if you are doing a different type of request, you can change this using the dropdown.

Under the request URL bar there is a tab ‘Auth’, and it defaults to ‘Inherit auth from parent’. I recommend leaving this setting across your requests so that you manage the authentication token at the folder/collection level. This will just save you time.

 

  1. In the ‘Enter request URL’ field, add the URL for the API endpoint from the API Browser. In this case, it is this URL: https://<[yoursubdomain].docebosaas.com>/manage/v1/user/{user_id}

A picture containing graphical user interfaceDescription automatically generated

 

In this call’s case, there is a placeholder, {user_id}, which lets you replace that with the Docebo ID of the user to look up.

  1. Select ‘Save’. This will keep your calls in between program sessions, unlike in the API Browser.
  1. Select ‘Send’.

Graphical user interfaceDescription automatically generated

 

  1. The response will load in the window either below or to the right side depending on your settings. All of the information in the selected user’s profile is displayed.

 

 

Ready for another example?

Let’s use the second example from the API Browser to look at how we can add parameters to the calls.

 

  1. Select ‘Request’ from the new menu.
  1. Give it a distinctive and descriptive name. In this case I’ve titled it ‘Get List of Users’.
  1. Make sure the collection you just made is selected (or if you have multiple collections, that the right one is picked).
  1. Select ‘Save’.
  1. The type will default to ‘GET’ which is what we need, but if you are doing a different type of request, you can change this using the dropdown.
  1. In the ‘Enter request URL’ field, add the URL for the API endpoint from the API Browser. In this case it is this URL: https://<[yoursubdomain].docebosaas.com>/manage/v1/user
  1. Select ‘Save.

Graphical user interface, text, applicationDescription automatically generated

 

 

 

Adding Parameters

Remember in the API Browser how we could run the call just like this? You can do the same now, but that is most likely not useful. Look underneath the request URL bar, and you will see a tab called ‘Params’ that has a table of Key, Value, and Description. This table will let us add the other settings from the API Browser.

 

  1. In the first Key spot put: sort_attr
  1. In the first Value spot put: last_name

You can add a description if you wish to remember more about this parameter. I sometimes put other choices/options here so I do not need to look them up again.

  1. In the next Key spot put: sort_dir
  1. In the next Value spot put: asc
  1. Select ‘Send’.

Graphical user interface, text, applicationDescription automatically generated

 

 

The results shown should match the same list you received in the API Browser. As an extra step, notice there is a checkbox to the left of each parameter. If you want to remove a parameter but remember the value for later, simply uncheck it and it will be excluded from the call. This is a great way to keep multiple common parameters and toggle which you want to use each time.

 

You can add as many calls as you want, organize them into folders, and sync between computers. You can do a lot more with Postman, so as you get more comfortable, make sure to search for some advanced lessons. 

 

That’s it, you have successfully configured Postman to continue your API explorations, enjoy!

 

 

Guide Series:

The Art of Being Lazy: Leveraging the API to Take Care of Repetitive Tasks & Fill Feature Gaps

Getting Started: Building Out Your Toolbox [Part 2]

Reports: Sending, modifying, and more!

In the Room When it Happens: Act On Events with Webhooks

Bulk Scheduling ILT Sessions with a CSV File

Tag, You’re It!: Tracking and Managing Content Tags

Let Others Do It: The Power of Forms in a Workflow

And We're Back: How to Let Users have a Form as a Wizard Scheduling Tool

You Built It, They Came, Now What?: Scheduling ILT Wizard Bonus Activities

 


10 replies

Userlevel 7
Badge +6

What have you done?

Userlevel 7
Badge +3

Just getting started @dklinger gotta do the pre-work to have some fun!

Userlevel 7
Badge +5

Oh la vache!

Userlevel 7
Badge +3

That’s a new one for me @gstager had to look it up, I like it * added to mental vault for future use *

 

Userlevel 7
Badge +5

I get this with attempt to get token - after successfully authorizing via popup

POST

Error: runtime:extensions~request: request url is empty

▶️Request Headers

 

Content-Type: application/x-www-form-urlencoded

Authorization: Basic bGVhZGluZy1yZTpjZDlhODZmMWNhOGZjODE2YTk2MmQwYjZmOTdlMTFlYjk1ZWMxYmNh

  • ▶️Request Body

    1.  grant_type: "authorization_code"

    2.  code: "bf17eb75ad4415abc0bf01e94ab58d8fd3dde297"

    3.  redirect_uri: "https://www.getpostman.com/oauth2/callback"

    4.  client_id: "leading-re"

 

Error: runtime:extensions~request: request url is empty

Userlevel 7
Badge +3

@lrodman Hmm, not sure I am completely following what you are trying to do. Just to make sure we are on the same page, are you on the parent trying to generate a valid token to use on individual calls, like here:

 

It also based on the response that you are using the authorization code grant type? I usually use implicit to avoid having any secure information stored, still requires you to log in essentially. Are you set to that and getting the pop up to log in and it comes back and then errors?

Userlevel 1

I’d just like to say thank you VERY much @Bfarkas for this guide and the series :) I link it to clients all the time and it’s ultra helpful and extremely well-written. Cheers!

Userlevel 7
Badge +3

I’d just like to say thank you VERY much @Bfarkas for this guide and the series :) I link it to clients all the time and it’s ultra helpful and extremely well-written. Cheers!

Thanks @andrew.charles ! Love to hear it. I was just joking the other night, now that this series is over, and the Quick Grabs is coming to a close…….brainstorming for new ideas :) If theres something that would be useful that keeps coming up, let me know!

Userlevel 5
Badge +2

@Bfarkas Thank you so much for these I’m watching the guides at the moment. I was wondering have you got any tips for showing more than one page of JSON code in the Docebo viewer. If there isn’t an option to change the pages. For example on the Skills, “Retrieve The Entire Skills List”. It only give you 15 per page and I can see there are 34 pages. I don’t have access to postmaster only Power BI.

Userlevel 7
Badge +3

@Bfarkas Thank you so much for these I’m watching the guides at the moment. I was wondering have you got any tips for showing more than one page of JSON code in the Docebo viewer. If there isn’t an option to change the pages. For example on the Skills, “Retrieve The Entire Skills List”. It only give you 15 per page and I can see there are 34 pages. I don’t have access to postmaster only Power BI.

Unfortunately, one of the limitations of the API Browser is that you are confined to only the parameters the browser supports, not a good way to inject changes to the calls. You will run into this a bunch unfortunately (especially on some of the newer items where there definitely seems to be a quality control issue on documentation correctly and robustly.

Does your org allow any type of development tool that can send http requests? There are a lot out there, I am sure they must have at least one that someone uses?

Reply