Thanks to slower pace blog update, I have been able to spend a hour a few days a week to pick up hacking again. I would call it hacking, not coding, and I want to draw distinction between the two because I see the difference. More on that later.
I was not interested in picking up a new programming language. The fact that the language that I had to use was C# didn't help. I cut my teeth writing Java and C as a coder. I decided to work with them early on because they were free and open. It meant I didn't have to go get a license just to write some code or distribute the source. I wasn't going to pick up Microsoft standard and write application that would only run on Windows environment.
Instead I was much more interested in coming up with a solution. I had a goal of building a tool that solves a problem that I had. C# was a means to help me create the tool.
Because I was dealing with a development environment that I was not familiar with, my strategy was to start with a sample code and start morphing it into a tool that solved my problem. I had a simple reason. If I start with sample code that already compiles and runs, I wouldn't have to worry about picking up the language syntax, going through the Hello World example, and fix compilation errors.
There were just one problem: sample code had to work as advertised. I picked up Exchange Web Service API sample code (retrieving Out-of-Office message sample code via EWS API), and built and compiled. Thankfully it compiled without any error, but when I started running, it didn't run. It turned out that auto URL discovery for Exchange service did not work in my environment for some reason. I had to find out what the service URL was and populate the URL manually.
Another bug was more subtle. When the sample code was run, it prompted for email address. But in reality it was expecting the user to type in username not the entire email address. It meant when I typed in username@mydomain.com, it failed to connect to our Exchange server consistently. Only after poking around and several google searches, I realized that it was expecting username only without @mydomain.com. Duh.
All it needed was a simple print message "type username of your email address ('john.doe' if your email is 'john.doe@domain.com')".
Only saving grace was that there were other developers who shared their code and suggested workarounds. Without their posts and comments, I simply did not have a chance to even get over the first hump. Imagine doing this soon after the API was released without all google results. I would have given up after a few minutes.
So what is the lesson for those who are setting out to build their own API? Here's my take away:
The project is migrating email to collaboration platform. I blogged about it earlier. One sentence description is to take emails in Inbox and post them on enterprise collaboration platform to be shared to internal audience. Minimum Viable Product is posting the emails that I select on my Outlook client (yes, I'm the user of this product) to collaboration platform, and have collaboration platform return the link where it's posted so that I can forward it to anyone who need to be included. Tagging the email so that I can search easily would be nice as well.
I use Outlook client for my work, and in order to access Exchange server, I had to use C#. I've never coded in C# before. I don't know any C#, and that's where my hacking began. I call it hacking because I didn't sit down to learn C#. I had a specific goal that I had in mind, which was to use Exchange Web Service API to access Outlook Inbox messages with special tags. I had to figure out a way to do it using C#, a language that I didn't really care to master, so I had to hack something together. That meant I relied on Google extensively to code and troubleshoot compilation errors. I began from working code sample, and what I have still very much resembles the sample code from MSDN. All my hacking was done on Visual Studio, and much of credit should go to autocomplete feature of Visual Studio.
While I was doing this hacking, I learned a few things. I wanted to share them with you to see if any of you felt the similar way. What I'm about to share is hacker's perspective. Someone who doesn't know the language or doesn't care to learn the language. All they are interested in is getting the stuff to work.
These are things that I learned.
I was not interested in picking up a new programming language. The fact that the language that I had to use was C# didn't help. I cut my teeth writing Java and C as a coder. I decided to work with them early on because they were free and open. It meant I didn't have to go get a license just to write some code or distribute the source. I wasn't going to pick up Microsoft standard and write application that would only run on Windows environment.
Instead I was much more interested in coming up with a solution. I had a goal of building a tool that solves a problem that I had. C# was a means to help me create the tool.
2. I want the sample code to just work.
Because I was dealing with a development environment that I was not familiar with, my strategy was to start with a sample code and start morphing it into a tool that solved my problem. I had a simple reason. If I start with sample code that already compiles and runs, I wouldn't have to worry about picking up the language syntax, going through the Hello World example, and fix compilation errors.
There were just one problem: sample code had to work as advertised. I picked up Exchange Web Service API sample code (retrieving Out-of-Office message sample code via EWS API), and built and compiled. Thankfully it compiled without any error, but when I started running, it didn't run. It turned out that auto URL discovery for Exchange service did not work in my environment for some reason. I had to find out what the service URL was and populate the URL manually.
Another bug was more subtle. When the sample code was run, it prompted for email address. But in reality it was expecting the user to type in username not the entire email address. It meant when I typed in username@mydomain.com, it failed to connect to our Exchange server consistently. Only after poking around and several google searches, I realized that it was expecting username only without @mydomain.com. Duh.
All it needed was a simple print message "type username of your email address ('john.doe' if your email is 'john.doe@domain.com')".
3. I want the API to be as small as possible, so that I don't have to invest time to figure out things.
As the sample code started compiling and running, I thought I got over the hump. I was wrong.
When I looked for reference guide for Exchange Web Services API 2.0, I knew exactly what I was looking for. I was looking for a way to save the message based on an extended property. But there were no place where I could find that enumerated all available methods from EWS objects.
I think the idea of organizing the doc by the tasks that developers can do with the API was a good one, but it was only as good as sample code and comments explaining how they worked. For example, the sample code to retrieve extended property by name did not work, and it didn't have line-by-line explanation of how the code was supposed to work, I had to rely on google to save the day. To make the matter worse, there were no enumeration of methods. I just couldn't figure out how to manually construct my hack.
What I had to rely on was many google results and Visual Studio suggested methods to find the right solution. That was not fun.
When I looked for reference guide for Exchange Web Services API 2.0, I knew exactly what I was looking for. I was looking for a way to save the message based on an extended property. But there were no place where I could find that enumerated all available methods from EWS objects.
I think the idea of organizing the doc by the tasks that developers can do with the API was a good one, but it was only as good as sample code and comments explaining how they worked. For example, the sample code to retrieve extended property by name did not work, and it didn't have line-by-line explanation of how the code was supposed to work, I had to rely on google to save the day. To make the matter worse, there were no enumeration of methods. I just couldn't figure out how to manually construct my hack.
What I had to rely on was many google results and Visual Studio suggested methods to find the right solution. That was not fun.
4. I want my answers to be Google-able.
Only saving grace was that there were other developers who shared their code and suggested workarounds. Without their posts and comments, I simply did not have a chance to even get over the first hump. Imagine doing this soon after the API was released without all google results. I would have given up after a few minutes.
So what is the lesson for those who are setting out to build their own API? Here's my take away:
- When building an API, use widely understood and easy to use language. Don't make developers to learn new environment to use the API.
- Make sure sample code runs as is. Chances are that will be the first thing any newbie will try.
- Explain the sample code line by line so that people who don't know the language can still hack up a solution.
- Keep the API set as small as possible and make them searchable. The smaller the API is, the more refined the API is.
- Create searchable community where developers can leverage each other's knowledge.
Hope this has been helpful to you. If you have comments or feedback, please let me know at jaeho9kim (at) gmail (dot) com. If you haven't, please follow me on Twitter: @jaeho9kim.
No comments:
Post a Comment