5 Mistakes that Can Destroy Your API Strategy

APIs have taken the industry by storm as front & center of mobile, cloud, and IoT, making it crucial to check for these common mistakes.

Service Oriented Architecture (SOA) and the “API-first” approach has proven to be extremely adaptable to integrations, and to serving as the core engine for supporting apps on various operating systems, mobile platforms, and wearable devices.

Because of APIs, we’ve seen Google Maps leap over MapQuest, Facebook eradicate Myspace, and Amazon Web Services bring cloud computing to the masses.

It is no wonder that a lot of industries are actively participating in the API space. I’ve been lucky enough to be a part of the API space for many years. Working with world’s most trusted API testing tool, SoapUI, and the Ready! API testing framework, I have seen APIs explode in use in government, manufacturing, financial technologies, and just about every other industry.

I’ve seen what works well for organizations that are new to the API space, and also the setbacks team can face when getting started. To help you avoid these setbacks, I wanted to share five of the biggest mistakes you need to avoid:

1. Treating the API as a single request/response interaction

The ‘A’ in API stands for ‘Application’. You should be thinking of your API as an end-to-end application. With a website or a mobile app, no one believes that doing comprehensive testing is to call a single page and check that the response is received while ignoring response content. However, a single endpoint call with a check for a successful HTTP status seems to be the standard test for an API.

The widely adopted BDD/TDD approach isn’t much better. Somehow people started thinking that checking off requirement specifications makes their API bulletproof. If you are currently thinking that, consider the following question:

“Would you buy a car where every button has been individually tested, but no one has ever taken that car for a test drive? Would you drive that car off the lot with your family in the backseat?”

The API should be treated as an application. API operations or different APIs, when integrated, are called in a specific sequence. You should interact with your API in the same way an end user would through their application. You should use real data against the API. You should check that your API scales to real volumes of user traffic.

A good API will make for an easy integration. However, if you focus solely on the user application instead of your API, then you are falling into the second rookie mistake…

2. Assuming your APIs are fine if your application is fine

Many people make the assumption that since your user application driven by APIs works, then your APIs are fine. This is like assuming that since your house is standing, then the house foundation is fine. This approach ignores all the cracks and structural weaknesses that could still be present. For APIs, the integration itself could be masking a lot of deficiencies. This will not hold up when you need to add new modules or use your APIs for other purposes or other applications.

Never judge a house by it’s cover.

Furthermore, when your application hits an issue, you have to troubleshoot every call in the chain. If your application is broken, you need to check your API, your integration layer and your GUI application. Whereas knowing if your API is working or not can save you loads of troubleshooting time by focusing your efforts to the right link in the chain. This will reduce the time to fix the issue exponentially

Some people would rather not put their focus on the APIs. They fall into the third trap …

3. Focusing on SDKs/DevKits too much

A lot of API providers have the best intentions for helping others integrate with their API by creating libraries (SDKs) in common programming languages like .Net and Java.

This focus on SDKs requires that team members know a number of programming languages. Also focusing on specific languages is detrimental to other companies and departments that might have picked something else entirely. There are apps written in Node.js, PHP, Perl, Delphi, etc. There is no way that your focus on SDKs can cover every programming language out there.

Additionally, the more SDKs you support, the more code changes have to be rolled out for every change in API functionality.

A final reason not to do this is that providing an SDK makes you responsible for any integration into your API. You will have to troubleshoot other company’s code, which is the last thing you want to dive into.

Instead, direct your focus on the API itself. In this focus on the API design make sure not to make the next oversight …

4. Not having a service contract for your API

SOAP protocol lost favor to RESTful services years ago. However, while moving on to REST people abandoned an important concept — web service descriptor (WSDL in SOAP). Anyone integrating with an external API would have a head start with a WSDL accompanying a SOAP API. This beats relying on PDF documentation accompanying most REST services. I’d estimate companies are wasting decades of work on needless meetings verbally communicating the behavior of a REST API.

There is a better way. There are numerous REST Description Languages available.Swagger, aka “OpenAPI Specification,” provides:

• Common descriptor that tech industry giants like Microsoft, IBM and Amazon have standardized on
• SwaggerUI that generates an interactive page that can serve as your API documentation (example)
• Ability to generate SDKs in 30+ languages
• In the API design first approach, you can generate code stubs from Swagger API specification in 15+ languages

For RESTful APIs, Swagger is awesome. If I did not convince you to adopt Swagger, standardize on something else. The key is that you should standardize on a descriptor that others can consume, to faster work with your API.

By broadening your view into considering REST Descriptor Languages, you can easily avoid the last pitfall …

5. Ignoring your API ecosystem

There is a lot of “if you build it, they will come” mentality in the API space. Countless technical departments are building APIs, following SOA and Microservices methodologies, because they feel they need to.

A majority of those teams never brought in an outside developer to observe how they would approach their API. How would that external person look at API specification, documentation, SDK or whatever else was available? What kind of obstacles would that developer encounter? What’s the team plan to empower other developers?

The same fresh approach needs to be taken with most revisions to the API. I have seen APIs that have outdated schemas and documentation and do not reflect the actual API. That is infuriating from an outside integrator perspective.

Make sure your product plans include the necessary checks and updates to documentation, specifications, and/or SDKs that you committed to support. Make sure those checks are done with every release. Keep an eye out for updates in security and API standards which might have changed. Find out how your APIs are used; I’ve seen many surprises where other parties found unexpected ways to utilize the API.

“My API looks so nice from up here!”

If you avoid all these pitfalls, your API will truly be ahead of the pack. You’ll be able to integrate with anyone and build apps for technologies that will be all the rage next year. Your application will scale and you will spend less time on troubleshooting and fixing other people’s integrations.

This article was written by Matt Giller & was originally posted on Smartbear’s blog.