Getting Started with APIs

Esper APIs are a set of REST-based endpoints that let you programmatically control and monitor devices running Esper Agent. Before interacting with Esper’s API, you’ll need to create an API key. See API Key Management for more information. 

Once you’ve generated an API Key, you’ll be able to create your first Esper API request. 

You’ll need: 

• An API Key 
• Access to the Console’s API Key Management 
• cURL or Postman

In this article:

• Why Use APIs?  
• Constructing the Request
• Making Requests 

Why Use APIs? 

What happens when we make a request? Requests are a way to interact with data within the Esper platform. In the Esper Console, there are many places where Esper interacts with data. For example, the device information, groups, and even your profile information are all data that Esper requests through its APIs. 

API requests allow you to interact with just the data you need. For example, you might want to gather device information to create your own data tables or delete deprecated app versions. The APIs create a way for you to manage and be totally in control of your devices and Console data. 

There are many resources to help understand REST APIs. This article covers the fundamentals for interacting with the API and goes over how to create your first API request. 

Constructing the Request 

If you’ve made requests to APIs before, feel free to scan through or skip this section. We also have a reference guide. However, if this is your first time creating an API request, we recommend reading through this section and constructing your first request in the sample exercises below. 

Each request contains: 

• The REST verb - The Esper APIs follow the REST architecture format and utilize GET, POST, PUT, PATCH, PUT, and DELETE. 
• The Authorization - Token Bearer <API Key> 
• The URI. The URI consists of: 
  • The tenant name 
  • The Enterprise ID
  • The URI 
  • The parameters (if applicable)
• The body (if applicable) 

The REST Verb 

REST APIs are APIs that follow the convention known as Representational State Transfer. REST uses verbs to identify what the request does with the resource. Are you just trying to view (GET) information? Create (POST) new information? Do we want to change (PUT/PATCH) information? Or remove (DELETE) information?

In the examples below, we’ll create a GET request to view information about the devices in our tenant. 

The URI

Let’s look at a sample URI (Uniform Resource Identifier, also known as endpoints). This one includes the REST verb. Once it’s constructed it’ll give us our tenant’s enterprise information.

GET https://{tenant-name}-api.esper.cloud/api/enterprise/{Enterprise-ID}

Notice this sample URI is missing some information. The tenant name is the same name that appears in the web address when you’re on the console.

The Enterprise ID appears in the API Key Management screen.

GET https://sample-api.esper.cloud/api/enterprise/1234567-a123-b123-7654321

Next, try constructing the URI using your own tenant’s information.

Authorization 

The URI isn’t the only requirement when it comes to creating a request. You’ll also need to include your authorization credentials (if you haven't already done so, generate an API Key). This ensures that only you can access your own tenant’s data. The Esper API uses the authorization type Bearer Token. Authorization credentials are written in the headers of a request. In a cURL request, for example, Bearer token is written as:

Bearer {API Key}

curl -X GET \
    https://sample-api.esper.cloud/api/enterprise/1234567-a123-b123-7654321/device/ \
    -H 'Authorization: Bearer 4ND1W45H3R3' \
    -H 'Content-Type: application/json' \
    

4ND1W45H3R3

Parameters

This is a parameter we’ve added to the request. Parameters are options passed to an endpoint. Take a moment to read over the information in the API documentation. 

You might notice sections such as security, the request, and more. One part of the request we haven’t talked about yet are parameters. You might have noticed the cURL request in Exercise #2 contained ‘/device/’ at the end. This is a parameter. (Note: the Enterprise ID is also a parameter!). Parameters specify which set of data we want to interact with. Think of them as folders. 

Putting It All Together

We’ve covered how to create an Esper API request using the following parts. Take a moment to review what each part means. 

• The Verb 
• The URI 
• Authorization 
• Parameters

Making the Request 

Now it’s your turn. Make a request using cURL or Postman.

curl -X GET \
    https://{tenant_name}-api.esper.cloud/api/enterprise/{enterprise_id}/device/ \
    -H 'Authorization: Bearer {api_key} \
    -H 'Content-Type: application/json' \

Once you’ve sent the request, you’ll receive information about the devices in your tenant. If you see something like this: "{}" it might mean there aren’t any devices in your tenant. If so, add a couple devices and try sending the request again.

There’s a lot about APIs we haven’t covered in this tutorial. To learn more about our APIs, see our API reference.