Basic Integration with the Easy Song Licensing API

To integrate with the API, you will need to write code to construct HTTP requests. The easiest way to do this is to use an existing HTTP client library in the programming language of your choice (C#, Java, Python). The HTTP client libary serves as an interface to communicate with the API. Your code serves information to the client library and does fun stuff with the data it returns.

What is an HTTP client library?

An HTTP client library is a bundle of code someone else wrote that you can use to access any resource on the web via HTTP (the language of APIs, including our API). It does the work of serializing HTTP requests (prepping data to send to the API) and parsing HTTP responses (breaking down information you get from the API into a format that's easy to interpret in your code).

Setting up your HTTP client libary

You should be able to find an existing HTTP client libary in the programming language of your choice. For example, check out the libraries available for the following popular programming languages:

• Google's Java HTTP Client
• .NET HTTP Client (C#, C++, VB)
• Python HTTP Client

Setting up your HTTP client might take a little work. For example, if developing in C#, you will need to add the necessary System.Net.Http library before you can use it. In Visual Studio, click "Tools | NuGet Package Manager | Manage NuGet Packages for Solution...". Then browse for "Microsoft.AspNet.WebApi.Client" and add it to your project. Similar setup steps may be necessary for the other libraries as well. For detailed help setting up other libraries, you'll need to do your own research online.

Make a simple request and see the response

After you have your HTTP client set up as described above, you are ready to make a simple request to the API. To make a simple request, do the following:

1. Create an instance of your HTTP client
C#
var client = new HttpClient;
VB
Dim client As New HttpClient


2. Set the default request headers with authentication information so that every request has this necessary information. Provide the word "Bearer" and your API Key.
C#
client.DefaultRequestHeaders.Authorization = New Headers.AuthenticationHeaderValue("Bearer", yourUniqueAPIKey);
VB
client.DefaultRequestHeaders.Authorization = New Headers.AuthenticationHeaderValue("Bearer", yourUniqueAPIKey)


3. Get all your licensees from the API.
C#
var response = await client.GetAsync("https://api.easysonglicensing.com/api/licensees");
VB
Dim response As HttpResponseMessage = Await client.GetAsync("https://api.easysonglicensing.com/api/licensees")
Important - When referencing API endpoints throughout this documentation, we remove our domain from the URL (we remove "https://api.easysonglicensing.com"). For example, instead of writing out the full https://api.easysonglicensing.com/api/licensees we shorten this to /api/licensees. This is easier to read and less repetitive. When constructing your paths, make sure to include the full URL like we do in this example. Also, please use HTTPS for a secure connection.
Note - The HTTP client function GetAsync and the path /api/licensees correspond respectively with the GET /api/licensees endpoint that returns all licensees. You can use other HTTP client functions and other endpoint paths for other purposes. For example, to add a new licensee, use PostAsync and /api/licensees (endpoint POST /api/licensees). View the reference to see all the available endpoints (paths). Also note that https is used for a secure connection.


4. Congratulations! You've connected with our API and made a simple request. Even if you have no licensees, you can confirm that your request was successful by viewing the HTTP response status code with a simple line of code:
C#
Console.WriteLine(response.StatusCode);
VB
Console.WriteLine(response.StatusCode)


5. To use the data from the response, read the JSON content and deserialize it to an object (or list of objects). From there, you can use the object as you wish.
C#

// Get the response content in JSON in a string.
string json = Await response.Content.ReadAsStringAsync();

// Deserialize the string into a list of objects.
List<Object> listOfDotNetObjects = JsonConvert.DeserializeObject<List<Object>>(json);

// Get the first list item.
var firstLicensee = listOfDotNetObjects[0];

// Serialize the list item in JSON and display the result on a form label.
LabelResponse.Text = JsonConvert.SerializeObject(firstLicensee);

VB

// Get the response content in JSON in a string.
Dim json As String = Await response.Content.ReadAsStringAsync

// Deserialize the string into a list of objects.
Dim listOfDotNetObjects As List(Of Object) = JsonConvert.DeserializeObject(Of List(Of Object))(json)

// Get the first list item.
Dim firstLicensee As Object = listOfDotNetObjects(0)

// Serialize the list item in JSON and display the result on a form label.
Me.LabelResponse.Text = JsonConvert.SerializeObject(firstLicensee)

Here's the complete code from this example:

// Create an instance of the HTTP client.
var client = new HttpClient;

// Set the default request headers with authentication information.
client.DefaultRequestHeaders.Authorization = New Headers.AuthenticationHeaderValue("Bearer", yourUniqueAPIKey);

// Send a request to the API to GET all licensees.
var response = await client.GetAsync("https://api.easysonglicensing.com/api/licensees");

// Get the response content in JSON in a string.
string json = Await response.Content.ReadAsStringAsync();

// Display the response status code in the console.
Console.WriteLine(response.StatusCode);

// Deserialize the string into a list of objects.
List<Object> listOfDotNetObjects = JsonConvert.DeserializeObject<List<Object>>(json);

// Get the first list item.
var firstLicensee = listOfDotNetObjects[0];

// Serialize the list item in JSON and display the result on a form label.
LabelResponse.Text = JsonConvert.SerializeObject(firstLicensee);

// Create an instance of the HTTP client.
Dim client As New HttpClient

// Set the default request headers with authentication information.
client.DefaultRequestHeaders.Authorization = New Headers.AuthenticationHeaderValue("Bearer", yourUniqueAPIKey)

// Send a request to the API to GET all licensees.
Dim response As HttpResponseMessage = Await client.GetAsync("https://api.easysonglicensing.com/api/licensees")

// Get the response content in JSON in a string.
string json = Await response.Content.ReadAsStringAsync();

// Display the response status code in the console.
 Console.WriteLine(response.StatusCode)

// Get the response content in JSON in a string.
Dim json As String = Await response.Content.ReadAsStringAsync

// Deserialize the string into a list of objects.
Dim listOfDotNetObjects As List(Of Object) = JsonConvert.DeserializeObject(Of List(Of Object))(json)

// Get the first list item.
Dim firstLicensee As Object = listOfDotNetObjects(0)

// Serialize the list item in JSON and display the result on a form label.
Me.LabelResponse.Text = JsonConvert.SerializeObject(firstLicensee)

Example project

We have a created an example project in C# that demonstrates authentication as well as GET, POST, and PATCH requests for licensees.

Next steps?

You are on your way to creating your own integration with the Easy Song Licensing API. Next up? Review our best practices, and then post a request.