How do you post an object using WebRequest.Create?

Question

I am working with the Balanced Payments API and trying to figure out how to create a customer.

https://docs.balancedpayments.com/current/api.html?language=bash#creating-a-customer

The address is passed as an object, though I am unfamiliar with how to pass anything other than a string. Here is the code I have so far which successfully passes a name and email address:

    Dim request As WebRequest = WebRequest.Create("https://api.balancedpayments.com/v1/customers")
    request.Method = "POST"

    ' get this information from settings in your web config.
    Dim userName As String = "API KEY GOES HERE"

    Dim credentials As String = Convert.ToString(userName & Convert.ToString(":"))
    request.Headers("Authorization") = "Basic " + Convert.ToBase64String(Encoding.ASCII.GetBytes(credentials))

    Dim postData As String = "name=John Doe&email=jdoe@domain.com"
    Dim byteArray As Byte() = Encoding.UTF8.GetBytes(postData)
    request.ContentType = "application/x-www-form-urlencoded"
    request.ContentLength = byteArray.Length
    Dim dataStream As Stream = request.GetRequestStream()
    dataStream.Write(byteArray, 0, byteArray.Length)
    dataStream.Close()

    Dim response As WebResponse = request.GetResponse()

    ' create a data stream.
    dataStream = response.GetResponseStream()

    ' create a stream reader.
    Dim reader As New StreamReader(dataStream)

    ' read the content into a string
    Dim serverResponse As String = reader.ReadToEnd()

    ' clean up.
    reader.Close()
    dataStream.Close()
    response.Close()

Answer 1

I peeked at the API doc and from the looks of it, you don't actually pass an object in the request. You pass a tag/value pair list of strings.

Here is an excerpt from the API documentation showing an example for creating a bank account:

curl https://api.balancedpayments.com/v1/bank_accounts \
    -u ak-test-oAm876JsVLRmHwrswIGZ1kaelufk8Cmy: \
    -d "routing_number=121000358" \
    -d "type=checking" \
    -d "name=Johann Bernoulli" \
    -d "account_number=9900000001"

In order to understand this example, you'll need the reference from curl, found here.

-u Passes the user ID "ak-test-oAm876JsVLRmHwrswIGZ1kaelufk8Cmy" with no password.

-d Indicates a tag/value pair in the HTTP POST body. As you can see, there are four lines, each representing one attribute of a bank account.

So unless something is terribly wrong, the following code ought to do it:

Dim postData As String = "routing_number=121000358&type=checking&name=Johann+Bernoulli&account_number=9900000001"
Dim byteArray As Byte() = Encoding.UTF8.GetBytes(postData)
request.ContentType = "application/x-www-form-urlencoded"
request.ContentLength = byteArray.Length
Dim dataStream As Stream = request.GetRequestStream()
dataStream.Write(byteArray, 0, byteArray.Length)
dataStream.Close()

If this isn't working for you please post additional specifics about the problem.

Incidentally, there's a trick to putting together a well-formed tag value pair list. If you create a NameValueCollection using the ParseQueryString static method, it is created internally as an HttpValueCollection and can be used to render querystrings. Check it out:

Dim myCollection as NameValueCollection = HttpUtility.ParseQueryString(""); //Create empty collection
myCollection["routing_number"] = "121000358";
myCollection["type"] = "checking";
myCollection["name"] = "Johann Bernoulli";
myCollection["account_number"] = "99900000001";
Dim postData as String = myCollection.ToString();  //Magic!!
Dim byteArray As Byte() = Encoding.UTF8.GetBytes(postData)

This will be a lot easier than building the strings yourself when your object has a lot of properties and/or contains data that require escaping.

---

Passing an object with JSON

The API documentation lacks any examples demonstrating the passing of objects. Seems we're going to have to guess. Boo!

I poked about on the web and it seems pretty typical and standard for a RESTful service to pass complex data structures using a format known as a json string (JavaScript Object Notation) which looks something like this:

"address" : { "line1" : "This is line 1 of the address","city":"Seattle","state":"WA"}

Here is a much more elaborate example but I would suggest starting simple just to ensure this is what the API wants.

Try hardcoding a simple json string following this pattern and pass it to the service just to see if it works.

If it does the trick, we can look at easier ways to build the json. If you're on .NET 4.5, check here. Otherwise you have to do just a little bit more work and implement your own function like this one or as explained in this article.

But the first trick is to verify my guess. It's a pretty good guess since the Balanced Payments API uses json in the response messages (as can be clearly seen in the examples). Try it and out and let me know what you find.

---

Passing an object using the Balanced Payments API's funny syntax

OK I kept poking around that API document and found a good example of passing an object.

curl https://api.balancedpayments.com/v1/marketplaces/TEST-MP5is34cQM5VCKcHcIfXxLGw/credits \
    -u ak-test-oAm876JsVLRmHwrswIGZ1kaelufk8Cmy: \
    -d "amount=10000" \
    -d "bank_account[routing_number]=121000358" \
    -d "bank_account[type]=checking" \
    -d "bank_account[name]=Johann Bernoulli" \
    -d "bank_account[account_number]=9900000001"

I infer from this example that the way to pass an "object" is to provide the object name and include its properties, one by one, in square brackets.

So in your case it ought to be

Dim postData as String = "name=John Doe&address[line1]=123 Main St&address[city]=Baltimore&address[state]=MD&address[postal_code]=21224&email=jdoe@domain.com"

etc.

Give that a try. Third time is the charm?