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:
- Lump all your values into a single parameter. It’s annoying for your developers
- Make me escape values so that they can be inserted into your database. It’s your database, you escape it before it is inserted.
- Ignore existing best practices and specifications for creating an API service by creating your own. Use REST or SOAP.
- Give your developers carte blanche access to issue select queries, but don’t provide them with any documentation.
When planning your API, DO:
- Use an existing specification like SOAP or REST so that your API is more widely accepted by the development community.
- Make your API as easy as possible for your developers by providing clear data requirements, providing concise and understandable error messages, and handling the petty little things like escaping output for them.
- Inform your developers when there is a change to your API.
Thanks for reading. If you’re interested in working with BIO on your next project, get in touch with us here.