We recently wrote some code to interact with an online service via their API. The service provider handles donation gifts and donor records. Their API is lacking in several areas. I want to highlight some of the more problematic issues.
Data Passing Madness
Normally what you find with an API is that the provider is using SOAP or REST, or sometimes something in between. Generally it involves passing name-value pairs or an XML document to the service and expecting a response. Not so with this provider. All data passed to the provider was sent through a single parameter. Where you traditionally would send param1=value1, param2=value2, paramN=valueN. This provider required all data passed in a single parameter like this: params=value1,value2,valueN.
This is irritating for a few reasons. First, I can't tell what was passed based on the contents of the call. All I see are a bunch of values. Second, the position of the values matters. It must, since there is no other way to know which parameter the value represents. If no value is provided, you must pass null. As in, the string "null". Request parameters typically look like this, but are usually longer:
...?login=username&pass=password&action=request_type ¶ms=10,N,null,null,null,Joe,Smith,null,1,N,null,null,null,null, null,null,null,10.00,null,null,null,null
It's just a bad idea to try to roll your own API when there are existing specifications like SOAP and REST. I just don't know why they would choose to do it this way.
I'm Looking to Escape...
Another issue we found was that some requests were failing. The error message from the service was an ODBC SQL error message from the database layer complaining about special characters in the value. We had an apostrophe in the value. At first I thought, well we should be escaping the input before we send it over to the API, our bad! Although after a while I decided that wasn't right. Why should I escape special characters on my end? What if the provider decides they're going to move to from MS SQL to another database one day. Now I have to update my code?
Sorry, but no, the service provider should take the input, escape it and apply value requirements to each parameter, and then perform the database action as required. I should only need to pass the data using the correct credentials and in the required formats. Something as trivial as escaping output before a database action shouldn't be up to the end-user/developer.
Just Let 'Em Query Directly! Why Not?
Finally, one of the "features" this provider espouses is that they offer "advanced" developers greater access to the database by allowing them to run queries directly. Yep, I can send pass through an SQL select statement and it will return an data set in XML format. Nevermind that I don't know how the data is stitched together on their end. Forget that there is no documentation for this "feature".
My guess is that this provider was getting requests from developers to open up their data to a wider variety of calls. This was the providers response. Perhaps someone needs to explain the idea of an API to the development team.
Conclusion
So in summary, when planning your API service, don't:
When planning your API, DO:
I've always believed that it is immensely important for any service provider to truly understand their client's business. What I see in the web design industry today is far too many web designers offering more form than function. Often there is a disconnect between their clients goals and aspirations and the end result. I attribute this to not enough time spent understanding the client. How can one solve any problem when they fail to understand the reasons the problem exists in the first place?
With this in mind, I was excited to be offered a chance to fly to Churchill, Manitoba to join one of our clients, Frontiers North Adventures Inc. (FNA) in seeing how their flagship product is delivered to their customers.
FNA is a much esteemed adventure tourism company. They have received a great number of awards and accolades, including a few for being an ecologically friendly company. Their primary product is the Tundra Buggy Adventure®, a tour which takes adventurous individuals out on a tundra buggy to view wild polar bears near Churchill.
If you are unfamiliar with Churchill, know that it is a small remote town located on the coast of Hudson's Bay in northern Manitoba. It is only accessible via rail or chartered air. Polar Bears migrate from the south through Churchill.
Offering a service of the magnitude that FNA does to their guests is no small accomplishment. It is a huge logistical undertaking. Prior to the season launch in late October, FNA brings everything they need into Churchil via rail or air. The manage a large operation. In Churchill they operate a giftshop, hotel, and the overall buggy tours that go out onto the trails. They have their own garage for continued work on one of their 12 tundra buggies.
Tundra buggy maintenance makes up a lot of the logistical issues. These behemoths are built with giant tires (think monster truck tires or large tractor tires), the frame and differential of an airport firetruck, a giant diesel engine from a semi-trailer, and an all aluminium frame. Read about the history of tundra buggies here.
I had the privileged to sit down for a discussion with Merv Gunter, President and CEO of FNA while we trundled around on the frozen tundra in search of polar bears. We covered some of the logistical issues and past weather-related and technical-related troubles he and his team have experienced in the past. Every minute was an interesting insight into what their company does.
We saw around 30 polar bears on our early November trip. I saw how politely FNA staff treated their guests, how seriously their drivers took the security and safety of every guest on the buggy, and I saw how smoothly their entire operation ran.
Every experience I had on the tundra helped me understand our client a little better. In the future I am sure that we will be able to offer services to FNA which are grounded in the understanding of the fundamentals of their business.
Welcome to the Notion Design blog. My name is Darcy Hastings and Notion Design is my company. We're a passionate and dedicated group of designers and developers. We've been building websites and web applications as a business since late-2002. Prior to that, we've all had our hand in the web development cookie jar in some way, shape or form since 1998.
Notion Design was founded on two principles: one, service your clients extremely well and two, produce the best code possible. We pride ourselves on fulfilling both of these principles on a daily basis.
In our travels we've seen and created a lot of cool stuff. So this blog will be a sounding board for some of the things that we think might interest people. Specifically, we will probably have something to say about PHP, Zend Framework (and other frameworks for that matter), Python, Django, web standards, information architecture, user experience design, and I'm sure a lot more.