At Xojo, we work with a lot of HTTP REST APIs. So many in fact that I’ve spent time creating custom test harnesses to make sure that whatever I was currently coding would be compatible as well as being a test suite just in case the API changed in some subtle way (whether it be a bug fix or an API refactor gone awry). The problem with the custom test harnesses is that they’re not very portable and you end up having to create a new one for each API that you interface with.
When we created the iOS app for XDC 2015 last spring, I decided to take a different route and try out a few of the commercial REST API clients to see if any of them would make my life easier. The one I settled on was Paw from LuckyMarmot, primarily for its support of extensions written in JavaScript.
There is a small library of extensions available on the Paw website, most of which are for code examples and that got me thinking… why not have examples of the request in Xojo code, both old and new framework so that I don’t need to do that by hand every time.
Examples
For the sake of this example, let’s say that we’re making a request to login to a fictitious API. The URL of this request is https://www.example.com/api/login, it expects that you will pass the username (name) and password (1234) as URL parameters and that a preshared key is to be included in the body of the request as JSON.
Paw comes with an extension for creating cURL requests and the output of that extension looks like this:
curl -X "GET" "https://www.example.com/api/login?username=name&password=1234"
-H "Content-Type: application/json"
-d "{"preshared-key":"QU^k9h36zdF8nx7Y"}"
Using our Paw extensions, the Old Framework Xojo extension generates code that looks like this:
// Login (Old Framework)
// Set up the socket
dim h as new HTTPSecureSocket
h.Secure = True
h.ConnectionType = h.TLSv12
h.setRequestHeader("Content-Type","application/json")
// JSON
Dim js As New JSONItem
js.Value("preshared-key") = "QU^k9h36zdF8nx7Y"
// Convert Dictionary to JSON Text
Dim data As String = js.toString()
// Assign to the Request's Content
h.SetRequestContent(data,"application/json")
// Set the URL
dim url as string = "https://www.example.com/api/login?username=name&password=1234"
// Send Synchronous Request
dim s as string = h.SendRequest("GET",url,30)
If you’re using the new framework extension, it generates code that looks like this:
// Login (New Framework)
// Set up the socket
// "mySocket" should be a property stored elsewhere so it will not go out of scope
mySocket = new Xojo.Net.HTTPSocket
mySocket.RequestHeader("Content-Type") = "application/json"
// JSON
Dim d As New Dictionary
d.Value("preshared-key") = "QU^k9h36zdF8nx7Y"
// Convert Dictionary to JSON Text
Dim json As Text = Xojo.Data.GenerateJSON(d)
// Convert Text to Memoryblock
Dim data As Xojo.Core.MemoryBlock = Xojo.Core.TextEncoding.UTF8.ConvertTextToData(json)
// Assign to the Request's Content
mySocket.SetRequestContent(data,"application/json")
// Set the URL
dim url as Text = "https://www.example.com/api/login?username=name&password=1234"
// Send Asynchronous Request
mySocket.Send("GET",url)
These extensions are available for download using the link below. Once downloaded, extract the folders into the Paw Extensions folder which you can reach by going to the Paw menu and selecting Extensions->Open Extensions Directory. Once they’re in there, you can make them available by selecting Extensions->Reload All Extensions.
Versions for the Classic Framework and Xojo Framework are available on GitHub:
CONCLUSION:
Paw is an excellent tool for storing and managing API configurations and examples, plus adding the ability to copy and paste Xojo HTTP socket code makes it an even better part of your library if you work with a lot of HTTP RESTful APIs.