The definitive guide to Embold APIs

This article will help get started with Embold API so that you can build an application or a custom integration using Embold API.

What can you do with Embold API?
Getting started with Embold API
Understanding Embold analytics data and available API endpoints
Accessing Embold API
Making your first API call

What can you do with Embold API?

You can build powerful applications using Embold API. From a simple Mac notification center widget to complex DevOps integrations, pretty much anything you can imagine! The idea behind our API is to empower you to use the power of our analytics in your workflows the way you want.

Getting started with Embold API

Before we start, you will need an Embold instance running (on-premise or cloud), where you have access. If you don’t have one already please get one here. Embold is free for open source projects, however, please note that open source accounts don’t support API access as of writing this article. We will be making it available at a later point in 2020.

If you need help setting up your Embold instance, please visit our product documentation. Here is how you set up your projects and repositories. Do you have trouble scanning your repository? Here is what you are looking for!

Once you have your repositories connected and scanned with Embold, we are ready to go.

Understanding the Embold analytics data and available API end-points

You can access ratings, code issues, anti-patterns, pull request related data and much more for a given repository using Embold API.

Endpoints are categorized as given below:

Projects: Add, delete or update projects, get the list of projects, etc.
Repositories: Add a new repository, get information about a repository, get the list of repositories, etc.
Users: Get the list of users, add new users, get user details, etc.
Scans: Scan a repository, get scan history for a repository, etc.

To understand more about what data is available at each end-point, I will recommend you to read our API reference.

Accessing Embold API

To make successful API calls we need three things.

Embold instance API base URL. Example: https://example.embold.io/api/v1/
An API endpoint to call. Example : /repositories
Embold Access Token to authenticate API access

To access Embold API you need to create an Embold Access Token. We will use this token to authenticate during our API calls.

Making your first API call

Alright, its time to get some action going! Let’s make our first Embold API call to retrieve some data. We will first use Postman (a simple API development and testing platform) to try out an API call. Later we will see how we can make API calls from a Node JS application.

Now let’s open Postman and make a GET request.

We are creating a request to get the list of repositories we have on our Embold instance. Also, note that I am creating a collection by the name Embold Hello World to which we will save our GET request.

Create an API call with the following values:

Method: GET
URL: https://example.embold.io/api/v1/repositories
Authorization: Bearer Token: <your_token_string>

To construct the URL, Just concatenate as : <your Embold instance URL>+”/api/v1/”+<desired API endpoint>
Use the Embold Access Token as Bearer Token which is our method of authorization.

When you click the Send button, you will get a JSON response as seen below.

The response, in this case, is a JSON array of repositories with their details such as overall rating (overallRating) and lines of code (loc).

[
    {
        "repositoryId": 131,
        "repositoryName": "aidos",
        "uid": "b66ec741b82aee65d674c404977eec89",
        "timeStamp": "2018-01-19T14:50:01.912Z",
        "repositoryType": "git",
        "snapshotId": 229,
        "languages": [
            "JAVA"
        ],
        "overallRating": "3.60",
        "loc": "687"
    },
    {
        "repositoryId": 3093,
        "repositoryName": "Aleth",
        "uid": "de53ea48d88c7e74a7190ae9aed29f84",
        "timeStamp": null,
        "repositoryType": "git",
        "snapshotId": null,
        "languages": [
            "CPP"
        ],
        "overallRating": null,
        "loc": null
    },
    {
        "repositoryId": 175,
        "repositoryName": "android-chess",
        "uid": "70a19bc8769045a4bebc17d2becd587b",
        "timeStamp": "2019-06-28T05:43:47.546Z",
        "repositoryType": "git",
        "snapshotId": 520,
        "languages": [
            "JAVA"
        ],
        "overallRating": "2.57",
        "loc": "11298"
    }
]

API calls from Node JS application

Now we will make the same API call (we made with Postman) from within a Node JS application. Making API calls from other language platforms will be similar.

To make our job easier, we will be using Axios, a promise-based HTTP client in our node project. So let’s import this node module into our project using require.

const axios = require('axios');

For the sake of simplicity let’s declare our three required parameters to make the API call as constants in our JS file.

const apiBaseURL = "https://example.embold.io/api/v1/";
const endpointToCall = "repositories";
const token = "your_embold_access_token_here";

Since there will always be a delay before we get the server response for our API call, it is a good idea to make an asynchronous function to make the call using the async-await strategy. To handle any error we will use a try-catch block.

We are using variable config to pass the bearer token in the header and additional sort and order parameters.
Now using the axios.get the method we will simply make the API call. Note that variable data is holding the response JSON, which we can log to the console or return for further processing.

var getRepositories = async () => {
  try {
    var config = {
        headers: {'Authorization': "bearer " + token},
        params:{'sortBy':'loc','orderBy':'DESC'}
    };
    const data = await axios.get(apiBaseURL+endpointToCall,config);
    console.log(data.data);
    return data.data;
  } catch (error) {
    console.error('cannot fetch repositories', error);
  }
};

Now our completed code looks like this:

// Import Axios

const axios = require('axios');

// Required parameters

const apiBaseURL = "https://example.embold.io/api/v1/";
const endpointToCall = "repositories";
const token = "your_embold_access_token_here";

// Function to get repositories list using API ncall

var getRepositories = async () => {
  try {
    var config = {
        headers: {'Authorization': "bearer " + token},
        params:{'sortBy':'loc','orderBy':'DESC'}
    };
    const data = await axios.get(apiBaseURL+endpointToCall,config);
    console.log(data.data);
    return data.data;
  } catch (error) {
    console.error('cannot fetch repositories', error);
  }
};

// Making the function call

 const repositories = await getRepositories();

Congartulations , you have made your first successful API call!

If you have any questions, please ask them in the comments section below.

API Extending Embold