The Treacherous Land of Undocumented APIs
Test and Monitor | Posted April 09, 2014

APIs have obviously gained a lot of momentum in business over the last few years. More than a “player to be reckoned with," APIs have turned into an economy in and of themselves.

Evolving from a rather simple use case – enabling easier computer-to-computer communication – APIs have turned into a sort of backbone and glue that holds the Internet, and to a large extent the Web, together.

But APIs have always had a problem, call it a caveat or a double-edged sword, and that is that they fill their purpose excellently. They enable computer-to-computer interactions. That’s it. Mere humans have only a marginal role in their purpose. Anybody who has created, worked with, or tested APIs knows what challenges this poses.

How do you, as a human, digest and interpret something that’s meant for a computer? The answer is: with great difficulty.

Understanding APIs

And within that question you  find the entire reason that SoapUI was created back in 2006 - and also the reason for its success! We needed an easier way to test APIs and, in the process, make them more understandable for us humans.

When it comes to understanding what an API actually does, essentially what requests it allows and what responses to expect from it, there’s varying degrees of learning curves. It is dependent on how complicated (or how large) the API is, how well-engineered it is, how complete the accompanying documentation is, and what protocol it is written in. APIs can generally be separated into its two most popular protocols: SOAP and REST.

With the rise of REST I would argue that the learning curve to understand an APIs functionality took a steep upwards turn. REST, in all its lightweight and flexible glory, is not great at explicitly showcasing what the API can do. Unlike SOAP, where all requests and responses are defined in the mandated(ish) WSDL, REST puts the burden to document the functionality on the API’s owner or developer. It’s totally optional. From a functionality standpoint, the API will function perfectly fine without clear explanations to the user on what, exactly, it is it does.

If you’re anything like me, and I’m sure a lot of university-level students can back me up on this, “optional” is a word that - to large extent - is synonymous with “not doing it.”  In the context of developing APIs there are a lot of reasons why the optional work of documenting functionality is overlooked or blatantly skipped:

  • You’re pressed for time, and completing a thorough documentation isn’t prioritized.
  • It’s all in your head, and since you (and your team) are essentially the only people who need to know how it works it’s not prioritized.
  • The API functionality is so simple that no documentation is really necessary.

In the first case, you, or your manager, is prioritizing poorly. Documentation of your REST API should be as, if not more, important as the code that builds it. If nobody understand how your API works, it doesn’t really matter how great its functionality is – it won’t get used.

In regards to the latter two, you never know how your API will evolve and who will be interfacing with it. Without documentation, you'll likely run into problems with on-boarding new hires on the development team, opening up the API for the public, and any added functionality to the API.

State of REST

This pretty much brings us to the current state of the REST API universe. There’s a multitude of APIs out there with little or no documentation of what they do or how to properly use them.

As a stringent tester who wants to understand - and sometimes even define - the boundaries of what the API does, it’s a nightmare.

Testing undocumented APIs means either having to debrief the API developer (if he or she is still around) or, even worse, trying to manually explore what the API does. This is time-consuming for everyone, and much more error-prone than working with a well-documented API. The end-result could be that your company provides an API that isn’t fully tested, with functionality and security flaws.

Enter SoapUI Pro’s REST Discovery feature.

In version 5.0 we've released a neat feature that tackles this problem rather elegantly. REST Discovery allows you to simply record your interactions with the API, allowing SoapUI to automatically create all the resources called by the API. This recording is done either via SoapUI’s own internal browser or, even more nifty, by setting up SoapUI as a proxy allowing you to use your native browser or mobile app.

All you have to do is navigate to your API, use it as intended (and if you’re a tester, as not intended), and SoapUI will creat all the resources called during your interactions directly in the test project. The time-savings and (perhaps more importantly) the relieved head-ache is pretty substantial.

But the fun doesn't stop there.

After you’re done recording your interactions you can optionally choose to let SoapUI create a full TestSuite from your interactions, in the order you did them. This means that setting up something like a login-addToCart-delete-logout TestSuite for an undocumented REST API should only take you a matter of minutes (or however long the real-world use case takes). Again, the headache-relief of this is massive.

Finally, since REST Discovery actually captures everything from headers to responses, if you need to set up a REST mock for this (something we also added support for in 5.0) it’s just a matter of a right-click after you’ve recorded. Since REST doesn’t explicitly define what responses are expected for its requests, setting up a mock is something that would normally require a lot of manual work. You yourself would need to enter what the response of each request should consist of manually. But with REST Discovery this is automated, and it ensures you are using real-world data.

But enough reading about tackling undocumented APIs – try it out for yourself. Hook yourself up with free 14-day trial of SoapUI Pro, try out the new features, and let us know what you think in our forums.

See also:


dfads params='groups=933&limit=1&orderby=random']