Eight Common Pitfalls to Avoid When Hiring a Freelance API Developer
It seems APIs are everywhere nowadays. Name just about any popular web app, like Facebook and Twitter, and it will have a public API.
You know they’re important, and now it has fallen to you to figure out how to hire an API specialist to do some API development or perform some API integration services for your company. But there’s more to the world of APIs than you might think!
If you’re not sufficiently acquainted with it, you may end up hiring the wrong type of API development consultant entirely. Read on to find some easy ways to avoid this and other pitfalls during your next hiring phase.
Not Knowing What You Need
Your first line of defense against hiring pitfalls is knowing a bit more detail about what they’ll actually be doing when they work for you. You may not want to get into the technical nitty-gritty, and that’s fine.
Think about it as the difference between seeking a veterinarian and a pediatrician. You don’t have to be trained in either of their fields to understand that it’s crucial. Not knowing this beforehand is a waste of your time and theirs.
1. Not Knowing the API Type
First of all, APIs can be used to describe everything from how you can expect a web service to act down to how you can expect hardware to behave. And everything in between.
You may be developing a C++ library API, for example. If that’s the case, sifting through REST API résumés is simply putting you behind schedule.
Start by getting yourself into the right universe: OS, software, language bindings, network protocols, HTTP endpoints—these all can fall under the “API development” umbrella but are far too specialized for you to expect interchangeability.
2. Not Knowing the Work Scope
API-related work has two main roles. Producer vs. consumer, publisher vs. user, API development vs. API integration services—these are all talking about the same concept.
The minimum to know about this is that it takes far more specific experience to develop an API than to use it or integrate it with others. Someone who was architected an API can perform API integration services, but not necessarily vice-versa.
If it turns out you’re developing an API, another common hiring pitfall is not knowing how complete your API is. Greenfield API development—especially in more crucial contexts, as we’ll see below—is best left to those with more experience.
Maintaining an existing API is easy enough for a programmer who isn’t actually an API architect, as long as they are skilled enough in the tech stack. You’re risking less future rework here than on a fresh project. And with one less crucial criterion to search for, you’ll have more people to choose from who are actually quite suitable for the job at hand.
3. Not Knowing the API Scope
This pitfall applies only to API development, not API integration. There’s a fairly natural correlation here: A public API will likely require more expertise than a private, business-to-business one. Internal APIs are generally the least critical here. And the most forgiving.
But it’s a matter of assumed scale. A low-key public API may have a smaller user base than a multinational corporation’s internal API.
For example, the internal API developer for a small business may not have even experienced a public API as a user, let alone have a sense of what constitutes good architecture and best practices in that scope.
Consider how far-reaching this developer’s work will be, and hire accordingly.
4. Not Knowing the Software Stack
This is true about any development hiring. Get briefly acquainted with the list of technologies your product uses or will use. An existing developer can help with this if it’s not documented properly.
The list may be in the dozens. Find out which are the most important to have a good handle on.
If you expect your next hire to be productive quickly, you’ll want to make sure that they are already comfortable with the operating system, programming language, and major framework(s) that you need to use, if any. A Windows developer who has never touched Linux, or vice-versa, is almost guaranteed to need extra time getting running.
These few details are quite important in helping you look for a suitable candidate, but they should take only a moment to find out from your team.
Not Having the Right Type of Experience
Now that you have some clarity around who you’re looking for, how do you know if a given candidate is up for the job? Clearly, this depends a bit on the above context, and in some cases our other hiring guides can help with more specifics.
But API development hiring in almost any context will share three common pitfalls; we also offer a fourth point for those of you looking at RESTful API development in particular.
5. Never Having Seen Change Management in Action
For external API development, this is especially important.
Your API development here directly affects API integration for whoever is consuming your services. Breaking compatibility means breaking functionality that’s associated with your brand, so careful change management is crucial.
Your candidate doesn’t have to have designed a public API before, depending on your expected scale. But they should have worked with any particular one long enough to experience how they handled change.
Ask for an example and for their opinion of it:
- What changed?
- How did it affect API users?
- Would they do it differently?
This should give you an idea of their competence level in this (potentially key) area.
6. Poor Documentation Habits
Ask for a documentation sample. If they don’t have a sample because of NDAs, that may be OK: Ask them to describe their ideal documentation and their habits, instead. Your hiring instincts will have to help you out here.
But if they do have a sample, have any developer vet it. The one doing the vetting doesn’t even necessarily need to be familiar with the tech stack.
Ask them: Is it complete?
Also ask: Are all descriptions and examples written clearly and understandably?
If either of these come back negative, think twice. You may have a brilliant developer, but documentation is the face of your API. API consumers must be able to understand everything they need to know from it. Otherwise it’s a bit like a keyboard without labels. You may eventually figure out what each button does, but only after you’ve deleted all your wedding photos.
Actually, that metaphor doesn’t go far enough. We’ve come across projects before that had APIs with undocumented interfaces that were implemented (but went unused), and documented interfaces that weren’t implemented.
Maybe that situation would be like a keyboard where half the labeled buttons aren’t actually hooked up to anything, and there are hidden buttons somewhere that actually do what you want.
Your API users won’t appreciate that.
7. No Experience Scaling
APIs are fairly high-level. This means that optimizing them to scale makes sense closer to the beginning of project development, if possible. On a greenfield public API, you’ll want an architect with scaling experience.
If you don’t have one to help in this area, your API developer should be qualified for double duty: They should know how to plan your API in a way that lends itself to an efficient implementation and scalable operations.
This could be as simple as integrating pagination, so your API returns only a manageable amount of data for a given call. If this isn’t something they would think to do from the beginning, you might need someone with more experience.
8. RESTful, but Never Heard of HATEOAS
You’re likely in the RESTful API market. (If not, you can skip this point.) We’ll avoid starting a minor holy war here by taking a side, but: A RESTful API developer should at least have stumbled across HATEOAS.
They may hate it (pun intended) and never use it, but an API expert will likely at least have a mild opinion about its pros and cons.
If they don’t, it may be an indicator that their experience and exposure are not wide enough for your application. Of course, that depends on its scope, as mentioned above.
REST Today, Gone Tomorrow?
Why bother getting up to speed with all the above points, only to have it be useless knowledge tomorrow?
For one thing, API trends don’t shift nearly as fast as some areas of the Web. REST has been around since 2000, and despite the fact that companies like Paypal have deprecated their SOAP APIs in favour of REST APIs, some people still consider SOAP a valid option for greenfield projects.
The point is, researching your own API development requirements right now is a good investment in relevance as far as management-level tech knowledge goes. And some requirements, like good documentation, never change.
After taking this article’s advice, you should be in a much better position to find and hire the most effective person for your project. Success!