What Should You Include?
The way I see it, there are three options here:
- Write a method for every single option in the existing API
- Only allow access to the methods you think you’ll need
- Only write the wrapper for existing needs, but allow access to the full API as needed somehow
Most implementations are going to use either the second or third option. The first, while a nice idea, is unlikely to be worth the effort unless the API you are writing your wrapper for is especially terrible. Of the two remaining items, which direction you should go depends largely on your target audience. The second one is probably sufficient for internal-use wrappers. After all, if you need access to an additional method you can always go and update your wrapper code to include it. I believe the third should be your goal for a wrapper you are publishing for others to use. While you know and should publish the intended use of your wrapper, it is unlikely that other users are going to have exactly the same goals you do. By taking the time
I believe the third should be your goal for a wrapper you are publishing for others to use. While you know and should publish the intended use of your wrapper, it is unlikely that other users are going to have exactly the same goals you do. By taking the time to allow access to the parameters and methods in the underlying API, developers can benefit from your wrapper, but still make it work for their situation. Rather than only being a square peg in a square hole, your are creating a square peg that can easily work in any squarish hole with minimal additional effort. This makes your potential user base exponentially larger without having to implement the first option.
How Do I Build It?
This could easily be it’s own post (or series of posts), but in the end, it depends a lot on the API you are working with, what your output will be, and what language you are working in. However, there are a few elements that are going to be common to most API wrappers and that is a good place to start. Depending on how in depth your wrapper is, you might not need all these items.
A way to build an API call and return a response. Create the URL, add the authentication, final formatting parameters, and hit “send”. Wait for a response and return it. You probably want to include some error handling here as well (what to do if your call fails, not necessarily if the response is an error message).
Actions that will be executed via the API. Unless you are writing a simple “I don’t want to deal with authentication” app, this will likely be the bread and butter of your wrapper. Translating things your user wants to do into API calls. This might not even be a one-to-one ratio of API calls to actions. In some cases, it might be that you want to take a set of data and do a series of actions based on that data. You can wrap all that into a single action and save yourself a lot of hassle.
Ways to deal with the returned data. You may or may not need this one, depending on your situation. If your goal is to translate the data into a form another system can use then this is the primary focus of your wrapper. However, if your calls don’t return anything more than success/failure or the data is already well formed, then you might just return the raw API response out of your wrapper.
How Do You Document It?
It seems that everyone wants documentation but no one wants to take the time to write it. Writing an API wrapper is an interesting situation where you are primarily translating a system that already exists. While there are certainly plenty of methodologies out there for documenting your work, the approach I’m taking with this project is to write the documentation before creating the code. I’m finding that it is offering me some serious benefits. First, it’s helping me to work through the API documentation and think about what I need to translate and what I can ignore (or write a pass-through for). Second, I’m essentially creating a to-do list for myself since I’ve got a list of exactly what I’m planning on delivering. This has an added bonus of being in a format that I can hand off to the user and say “what do you think of this proposal?” before getting too far down the rabbit hole. Finally, I don’t have to write it later so it’s more likely to get done. Of course, I’ll need to make adjustments as I work, but by creating my plan in this format I can just hand it over with the code rather than having to translate an internal document to an external one. Anything I need to be internal-only (keys and such) is stored separately so I don’t need to worry about accidently allowing those things into the wild.
Writing an API wrapper is something that a developer will probably have to do many, many times over the course of their career. While each implementation will be different, it’s worthwhile to have a sound strategy for tackling this problem that you can reuse each time this task is set before you.