What’s an API? An explanation for the layman

So working as a web developer, I work with a lot of APIs. I’m also frequently asked things by non-coders about our API and the APIs of other sites. The concept of API seems to be that of some magical coding device that solves problems. However, while this is an amusing concept, it’s not entirely correct. In trying to explain the details of this to a coworker the other day, it occurred to me that I needed a good parable. So here you go:

Imagine if you would, a grouping of small islands in the middle of an ocean. Many islands are rich in coconut trees, but one is favored by schools of fish for it’s shady rock outcroppings near shore . Between these islands are a number of conveyor belts, capable of holding a small amount of weight. Each island is inhabited by a single individual. The islands are too far apart for speech, and they have long since run out of anything to write on, so the individuals are left to communicate by a pre-agreed upon system. They send across pebbles on the conveyor system, with different numbers corresponding to different messages. An example exchange:

1 Red rock + 2 Blue rocks = What kind of fish do you have today?

1 Red + 1 Green = 1 Cod + 1 Tuna

2 Red + 2 Green = **Bad data — not translatable** — (Should a non-agreed upon message be passed, it will not be understood)

4 Green = Message not understood. Please resend

1 Red + 2 Green = I’ll take the Cod please

2 Blue + 2 Green = Will do, please send 2 coconuts in exchange

Now this is of course a simple nonsense exchange, and it’s not very intuitive system, but in creating a communication system which allows them to exchange information over the conveyor belt (which is our metaphor for the copper or fiberoptic lines of the internet, these men have created an API. In it’s simplest sense, and API is a predefined system for communication, allowing two parties to share information. While many API share similarities, each data provider is free to set up their API however they want, both in terms of how the requests are made and how they respond to requests.

As you can see, there’s nothing magical about this. In a practical sense, any data that your company or site wants to allow others to read or write can be built into an API, some takes longer than others to expose in an intelligible manner. For example, a request to “give me the username and email for a user with id=300” is simpler than something like “give me the social graph of usernames connected to the user with id=300.”

Obviously, providing your data in such a manner could be a security problem, so often times API’s will be locked down to only users or other sites making requests with appropriate keys or perhaps the site providing the API will limit the number of requests per hour. There are a number of technical considerations that can are are made in designing an API, but I’ll save you from and other complications here.

Hope that helps. Feel free to post question in the comments, and I’ll try to explain.

Mahalo 4.0 Launched

Last Tuesday morning, after 6 months of working on it, the Mahalo team launched our newest version of the site: Mahalo 4.0. I have a lot of thoughts on what went well and what could have been better during the whole process, but I’m going to save those for later. We had a nearly flawless cutover (technology-wise) It total our downtime was only about 3 hours, and for most of that it would have been unnoticeable to most visitors.  Not bad for a complete rewrite of our backend storage layer and our front-end js/css/html. We’re still working on some bugs, but that was to be expected.

Check out this video to hear our development team talk about the new site:

Lessons Learned from a Coding Sprint

We spent the month of October at Mahalo pushing really hard on the tech side of things to try to get some new products built. The plan was to set aggressive goals in the past few weeks of September and then spend October trying to complete those goals for every team. If we met the goals, then each team member would get a reward. It was a great chance for the team to really show what they were capable of and bond through their mutual struggles. (and from a more stoic standpoint, help them appreciate the times when they’re not sprinting.)

Seems like a pretty simply plan right? Well it is/was, but I learned a lot along the way.

Pre-Sprint

1) Pick a date range for the sprint as early as you can. This isn’t always easy, suppose perhaps you are invited to launch a new feature at a conference in a month. Yet if you have a larger project and more runway, giving your team as much warning as possible is valuable. Engineers (and most people) like to be able to plan things, and even though you may be ok with them missing a weekend day or two because of previous plans, they may feel like they’re letting the team down by not being there. Don’t put people in this situation if you don’t have to.

2) Provide detailed expectations The more accurately you can detail what is expected in the month, the better everyone can plan their time and coordinate efforts. I came up with a list of things that we wanted to get done and some rough estimates for how each item would take. From there I pulled out a reasonable, but aggressive schedule for the month. I ran this list by my team to see if they thought I’d missed anything important or if my estimates were off. This doesn’t need to be perfect, but everyone can be a little more relaxed when they know what’s expected and have had a chance to vet it for accuracy.

3) Pick a reward We have a very motivated team at Mahalo, but even so, working extra hours can be hard on the psyche. Having something to look forward to at the end of the sprint is nice. Hopefully your team will be proud of their accomplishments and enjoy the camaraderie during the sprint, but having a physical reward is important. It’s tangible. This could be anything from a cash bonus to some time off to some sort of gift. After some discussion, we decided the best thing to do was head to a nearby shopping center and give everyone the opportunity to buy something they wanted within certain limits. (Also as a side note, we required that everyone use part of their money to buy some sort of totem to put on their desk at work — that went over well.)

During the Sprint

During the sprint I saw my job as two-fold: Getting people things they needed to get their jobs done and progress the product forward (product decisions, design mocks, etc.) and keeping people happy. The first is more important up front and the second becomes more important as the sprint progresses, but both roles are active throughout. As much as possible, I tried to stay as late as my team stayed and never ask them to do things which I wouldn’t do myself. That said though, as a leader, you need to take responsibility for being on top of your game and in a good mood. If you’re grumpy and tired because you stayed too late, that could have a more adverse effect than ducking out a little early one day. Don’t do it every day, but remember to take care of yourself.

On that note, people might get grumpy during the sprint. Remember to be patient and to warn others in the company, otherwise some poor guy from the sales department might end up getting snapped at for asking a reasonable question at the wrong time.

People aren’t machines, they’re fallible, and such long hours and hard thinking are going to take their toll. Hopefully the following can help:

1) Architect up front Do as much planning and architecting as possible at the beginning of the sprint. As the sprint progressed, we all noticed a decrease in brain-power. If you can front-load the sprint with the majority of the hard thinking, you can avoid making mistakes you might regret later because of fatigue.

2) Don’t expect peak performance at the end People are going to get tired, output is going to faulter towards the end. No matter how energetic and motivated your team is, coding 10+ hours/day, 6 days a week is going to wear them out eventually. On this note, you can help out some by keeping weekend days short if you notice people getting burned out and trying to avoid having people stay late to put out fires if possible. We also made the mistake of planning the sprint for 1 month. By the time the 4th week rolled around, I was polled the team to get a feeling for how everyone was doing and nearly every developer independently said something along the lines of: “man, I was doing great up until the end of last week, but now my brain is fried.” I would definitely say that if you have the option, plan the sprint for either 2 or 3 weeks. This will mean minimal performance degradation at the end and minimal cool-down time post sprint. We’ve also had some 10 day long sprints at Mahalo, and they seem to have about a 3-4 day cooldown period. The month long sprint has been about 7-10 days for most to start to feel like they’re getting back into things again.

3) Use some common sense Developers are, in 99% of cases, more important than due dates. If someone is getting visibly distressed or burned out, send them home early or give them a day off.  This one is really a gut call. Some complaining is inevitable, so you’re going to have to realize the difference between this and someone who is truly suffering adverse effects from the hours.

4) Keep people fed As trivial as this seems, food is primal, and people respond to it. It’s nice to be taken care of. It saves developers time and energy to not have to take off on a weekend or late at night to go find food. If you can provide them with some, it’s win-win. This could really be a blog post unto itself.

Post Sprint

1) Recognize People After the sprint, it’s best to let people enjoy what they’ve done. I think often-times is tempting to just accept what’s been done and move on to the next thing. As backwards as it seems, you may have to force people to show off a little bit. At Mahalo, we took an hour or so and had an all-company meeting to show off what we’d accomplished and discuss what was coming next and some of the reasons for why we’d been working on what we’d been doing. I made a point to have every developer talk, even if just for 30 seconds. Everybody contributed, so everyone should get a chance to be recognized.

2) Reward People This is as simple as following through on the plans you made earlier for rewarding employees. If you can go a bit above-and-beyond that makes a difference too. Just giving them what was promised counts for a C. You want an A+. Throw in a nice dinner and some drinks or some sort of company sponsored activity. Yay, teambuilding too!

3) Let People Relax One last thing to remember is to be patient in the cooldown period from the sprint. Everyone’s brains are fried. They’re going to need some decompression to get themselves back up to full capacity and get rid of that caffeine addiction they acquired (true story).  Cleanup work is a good thing to do during this period, there’s likely a lot of it around, and it’s menial enough that people can sort of recuperate while doing it. Another thing we encouraged at Mahalo was people leaving early. Early at Mahalo is like 6:30-7, even so though, I found that having an extra hour each night was great.

One other quick note: During this period, try to refrain from saying things like: “This is awesome, good work, but why don’t we add…” This can be a really tempting trap. Just remember your suggestion in your head, write it down, and save it for a week. No one wants to hear about the next 16 tons right after they finished hauling the last 16. It’ll get done, don’t worry.

I certainly made some mistakes during the sprint, but we managed to do some stuff right. Only time will tell exactly what the outcome will be, but hopefully I can save others from learning the hard way, and save your teams from having to deal with your mistakes. :)