On Building an API
A few months ago we announced the availability of the Lionbridge onDemand Public API. While there are many translation APIs in the marketplace, I think that ours is the most comprehensive. Most translation APIs offer one level of translation quality (for example, machine translation or crowd translation or professional translation). The onDemand API allows you to select a translation type that meets your needs. This means that you can integrate with one API and give your customers lots of options. We also support many different content types. For example, we can translate videos as well as basic documents. Lastly, we offer different payment options. The end customer can pay themselves or the money can flow through our integration partner. I think these differentiators are responsible for the rapid adoption we are seeing. We already have around ten third party integrations in production or nearing completion.
Personally, this has been a huge learning experience. While I have used many APIs and even helped developed a couple, this is the first time that I designed one from a blank page. The sheer number of approaches, options, and details that you face is enormous. And although the biases formed from personal experience are important, what really matters is the developer audience — not just in the decisions you make but also how you support them.
I hate the term best practice but here are some of the things we got right. I must admit that we didn't always land on all of these practices the first time but when we adopted them, we definitely saw results.
- Learn from others. When first designing the API, I drew inspiration from other APIs that I liked to use. I also found great information from George Reese's The REST API Design Handbook
.
- Get feedback. When first designing the API, I had the benefit of knowing who the first customers would be. I wrote the initial specification in a Google Doc and invited feedback. The first partners caught some important omissions and had some great ideas too. I also had different developers review the specification before development started.
- Be pragmatic about change. An API is a contract. It shouldn't change. However, in the early going there were a few cases where it made sense to change the specification. This was inconvenient and awkward for developers who are starting their integrations. However, it was much less painful than making changes later when the install base is bigger and changes would break working systems. Managing these changes requires a lot of humility (admitting you are not perfect) and effort to rebuild trust. Once the lead integration partner was getting close to being feature complete, however, we did lock down the version of the API and saved our changes for subsequent versions. Since the initial launch of the API to our beta partners, we have launched another version and are now working on a third. We handle versioning with an HTTP header so it is easy for a client application to update the version to get access to the new feature.
- Hire your first client. While any early beta customer will need to accept some level of instability, you don't want to risk a partnership with your earliest growing pains. For this reason, we hired a contract PHP programmer to develop and test code samples for working with the API. This external developer had no more access than a true partner developer would have. The experiences of this developer gave tremendous insight. It exposed ambiguity in the documentation where the API implementer interpreted different meaning than an external reader. It revealed cases where the test passed but externally developed code didn't work.
- Give client developers a plan of action. Like with most API's the hardest part of working with the onDemand API is authentication. For this reason, we recommend a development sequence that starts with the easiest API: List Services. We also wrote up a quick tutorial with a code sample to help. For our beta developers, we created a project plan template that developers could follow. It contained tasks for integrating with the various features and rough time estimates. I was surprised to learn how much the developers liked this. Personally, I hate being given a project plan that I had no input over.
- Provide fanatical support. Even though I love software development, I am the first to admit it can be frustrating. It is easy for developers to get bogged down and stuck. The smoothest implementations we have had were when the dev team actively engaged the client developers. I admit that sometimes I felt like my time was being stretched too thin. But when you think about it, how can you get more leverage than helping a partner use your service and bring you business? I also enjoyed working with external developers. First of all, they are savvier than regular business users so you can rule out silly things like being disconnected from the Internet. Second, it was fun to troubleshoot with them as they sent requests and we inspected what onDemand received. Pinpointing errors can save a client developer a lot of time. This work had the side benefit of improving our error handling to provide more informative responses.
- Treat your development sandbox like production. This should sound obvious but a lot of services that I have integrated with have very unstable developer sandboxes. They are not always available and they have issues that you don't see in production. There is nothing more frustrating than trying to fix your code and realizing that the problem is in an external system you are integrating with. For this reason, we manage the sandbox as a production environment. It gets the same monitoring as a production environment and we release new code to sandbox after it has been in production for a couple of days.
- Test like you mean it. Software is incredibly picky about the slightest detail so API testing needs to be extremely thorough. You can't just verify that you are getting data back. The data you get back needs to be precisely like what is in the documentation. For this reason we do what I call double-blind testing. The development team writes tests that run whenever new code is merged into the integration branch. An external QA team writes and runs tests based on the documentation whenever we have a release candidate. The hope is that having two independent approaches will everything. When it doesn't, we have a major debrief.
If you do it right, an API can revolutionize your business by opening channels that extend your reach. But getting it right requires commitment and attention to detail. If you underperform in any aspect (design, implementation, or support) your program is doomed. You won't always get everything right but if you maintain your focus and address your failures, you can get things back on track.