Monday, March 21, 2016

Using Basic HTTP Authentication in Haskell

I have recently developed a Haskell library to interact with the Mailchimp JSON API version 2.0. This is the blog post regarding the implementation of the said library. At the end of the blog post I stated, that I will try and update the library to support the version 3.0 of the JSON API. Since the version 2.0 is deprecated long ago and I had some free time in hand, I decided to develop the library to work with version 3.0 API calls. To read further more about the version 3.0 refer to this link.

The major difference in version 3.0 API from the version 2.0 API you need to know in developing the library is that, the removal of API Key from the request body and introducing HTTP Basic Auth in addition to OAuth2. In this implementation, I have used Basic HTTP Auth imported from 'Network.HTTP.Conduit' module in 'http-conduit' package. For further reading on the differences between the two Mailchimp API versions, please follow this link.

The major component in developing the library for version 3.0 was to integrate Basic HTTP authentication with the API calls.  In this post, I'll take you through the implementation of Basic HTTP Auth in the library.

There are 2 basic HTTP requests we need to perform in this library. They are GET and POST requests. For GET requests, the request body is empty while for POST requests we need to send data along with the request. I have implemented 2 separate methods to perform these requests in the library. 

The POST requests in Mailchimp JSON API version 3.0 looks as follows;

    curl --request POST \
  --url 'https://dc.api.mailchimp.com/3.0/campaigns' \
  --user 'anystring:apikey' \
  --header 'content-type:application/json' \
  --data '{"recipients":{"list_id":"et43235dg"},   "type":"regular","settings":{"subject_line":"this is the subject","reply_to":"reply@gmail.com","from_name":"from Mailchimp"}}' \
  --inlcude

So there are two parts for the HTTP request, i.e. authenticate the user and send the json data to the given URL. I used the the 'applyBasicAuth' function in the 'Network.HTTP.Conduit' module. The type definition for this function is as follows;

applyBasicAuth :: ByteString -> ByteString -> Request -> Request

The parameters are passed as 'applyBasicAuth 'username' 'apiKey' $ fromJust $ parseUrl url'Here, what 'applyBasicAuth' function does is attach a Basic Auth Header to the given Request.

In Mailchimp the username for the HTTP authentication is 'anystring', so I have hard-coded it within the functions.

Then we inject the json data to the request body of the resulting Request and the HTTP method to POST. Finally using 'httpLbs' method in 'Network.HTTP.Conduit' module we perform the action we intended. The full code snippet for this function is as follows;



For HTTP GET, the format of the request specified in Mailchimp JSON API version 3.0 is as follows;

    curl --request GET \
  --url 'https://dc.api.mailchimp.com/3.0/lists' \
  --user 'anystring:apikey'

This request retrieves data for all fields regarding each mailing list in the given account. But, if you want to receive only a couple of fields you can specify them in the request. To receive only the list ID and name for each list in the account, the request can be modified as follows;


    curl --request GET \
  --url 'https://dc.api.mailchimp.com/3.0/lists?fields=lists.id,lists.name' \
  --user 'anystring:apikey'

For the GET requests, what I have done is; remove json data injection for the initial request and setting the HTTP method as GET instead of POST. So the function to process HTTP GET request is as follows;



You can get the full program from my GitHub repository. I hope this post will be helpful for you!! Enjoy :)


No comments:

Post a Comment