Web Service Reference Documentation: Getting the Information You Need to Test


Lack of information and access to information isn’t an issue with web services. Web service documentation is widely available.


One of the major persistent complaints from people who test is lack of information and lack of access to information. Luckily this is not the case with web services. If in the rare case with some odd web service that you do lack information, it is fair to ask for more information.

Essential for testing web services is knowing what’s going on. Since a producer wrote it as a function to share, you, the consumer, probably do not know the details needed, or a resource person, for great test design.

Luckily, the web service and social API documentation will probably have the information you need. The documentation usually contains information about accessing the sandbox, getting a test account, data types, formats and, sometimes, boundary data and error handling.


The following information assembled at Wikipedia.org is a guide to the type of information commonly available for the integration and testing of web services.

API Reference Wikipedia: Documentation


The reference documentation for an API is an intrinsic part of any API, and without it the API is unusable. Every aspect of the API, no matter how trivial, should be stated explicitly.

When an API documents a library of functions in a procedural language, it should include:

function names

An object API should document:

  • the relationship of any type to other types: inheritance (super-types, sub-types, implemented interfaces or traits), composite structures, delegating entities or any mixed-in set of functionality
  • the public part of an object derived from a class definition, hence:
  • its public constants
  • the name and type of the member variables (fields or properties) that are directly accessible for any object
  • the signature of the class methods including information similar to that for functions in procedural languages, possibly including a list of getter and setter methods used to access or modify encapsulated information
  • any class-specific operators, in case the language supports operator overloading
  • indication of whether the fields or methods have a static nature
  • any constraint that applies to the objects one can create
  • nested structures, like inner classes or enumerations.

An API in a language using exception handling should report any kind of exception possibly thrown and the specific condition that can cause it to happen.

An API that can be used in a concurrent environment should include indications on how its behavior changes due to possible concurrent access to it: general usability in a concurrent context and possible race conditions.

An API with unstable parts should document them as unstable.

An API with deprecated parts should document them as deprecated.

An API that implements a communications protocol should indicate its general behavior, which should include details on:

  • how to set up a communication session based on that protocol and prerequisites for a correct setup of the communication session
  • if the communication is state-full or stateless
  • in case of state-full sessions: how the state is handled
  • the notation for the kind of messages that the protocol can transport
  • how communication errors are handled
  • if, in case of communication errors, a message resubmission can happen
  • the security levels supported, and how to secure the communication
  • any authentication required to set up the communication session
  • if the communication can be associated to a transactional processing, and consequently how to handle the transactions
  • if the communication can be embedded in an extended conversation, and consequently how to
    handle the conversation.

A graphical API should document:

  • the kind of graphical elements that can be handled
  • how to render the graphical elements
  • how to lay out the elements on the graphical canvas, and how to compose them
  • how to interact with the graphical elements
  • how to handle the user inputs, e.g.:
  • how to add callback to specific user events,
  • or how to read information from input fields

An API used to interact with a device should document the interaction with it, and hence:

  • how to access the device to extract data from it
  • how to modify the state of the device, when possible
  • how to detect error conditions in the device.

An API should always indicate what it applies to: version number of the language, of the library, and of any other resource it depends upon, the version of the protocols it is compatible with or that it implements, if any, and the version of the operative system or platform it supports.

An API that can be used in multiple languages via some form of language inter-operation should document any
restrictions to its use in case of usage with languages different from its native language.

API documentation can be enriched using metadata information: like Java annotation, or CLI metadata. This metadata can be used by the compiler, tools, and by the run-time environment to implement custom behaviors or custom handling.

Some examples:

If you have not accessed web service documentation, check some out. You may be surprised at the information and/or tools available to you to help with your testing.

Google Wallet

GoogleWallet API:



Testing and Test Flows:



Overview: https://developer.salesforce.com/docs

Developing and Testing with Sandbox:


LogiGear Corporation

LogiGear Corporation provides global solutions for software testing, and offers public and corporate software-testing training programs worldwide through LogiGear University. LogiGear is a leader in the integration of test automation, offshore resources and US project management for fast and cost-effective results. Since 1994, LogiGear has worked with hundreds of companies from the Fortune 500 to early-stage startups, creating unique solutions to exactly meet their needs. With facilities in the US and Vietnam, LogiGear helps companies double their test coverage and improve software quality while reducing testing time and cutting costs.

For more information, contact Joe Hughes + 01 650.572.1400

LogiGear Staff
LogiGear Corporation provides global solutions for software testing, and offers public and corporate software testing training programs worldwide through LogiGear University. LogiGear is a leader in the integration of test automation, offshore resources and US project management for fast, cost-effective results. Since 1994, LogiGear has worked with Fortune 500 companies to early-stage start-ups in, creating unique solutions to meet their clients’ needs. With facilities in the US and Viet Nam, LogiGear helps companies double their test coverage and improve software quality while reducing testing time and cutting costs.

The Related Post

These are the popular authentication methods in TestArchitect Authentication in API testing is usually a complicated subject for both developers and testers since it requires extensive knowledge on various types of security protocols and encryption algorithms.
API: An application programming interface (API) is a set of routines, protocols, and tools for building software applications. An API expresses a software component in terms of its operations, inputs, outputs, and underlying types. An API defines functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface. Source: https://en.wikipedia.org/wiki/Application_programming_interface
APIs are the unsung hero of our connected world We live in an exciting age of intelligence, where progress moves at the speed of imagination. We are connected to the world and one another like never before. API (Application Programming Interface) is the unsung hero of our connected world. Here’s everything you need to know ...
APIs are subtly altering our expectations that there should be an app for everything. The concept of disruption has been given regal status across businesses, startups, and tech circles in recent years. With such great emphasis placed on change, user experiences are inevitably facing evolution as well. Application programming interfaces or APIs have great transformative powers to disrupt business, but are ...
 Understanding the pieces of the web service testing puzzle can make testing easier For people wanting a broader understanding of more pieces in the web service testing puzzle, here is a breakdown of the various possible components of an API.
An API provides much of the functional capabilities in complex software systems. Most customers are accustomed to interacting with a graphical user interface on the computer. But, many do not realize that much of the functionality of a program comes from APIs in the operating system or the program’s dynamic-link libraries (DLL).
API testing has long been misunderstood as well-confined in the territory of developers. It’s natural to think that we must write code to test our code. However, it doesn’t have to be that way anymore. Business testers who have deep domain knowledge are now able to take on the challenges of API testing without coding. ...
API testing is different from GUI testing, but it doesn’t take long to master. What is an API? API is an acronym for Application Programming Interface. It enables communication and data exchange between two separate software systems. A software system implementing an API contains functions/subroutines which can be executed by another software system.
Here are some books you might find useful when developing your web services API testing strategy. The Art of Application Performance Testing by Ian Molyneaux — This book was just released and I found it an outstanding conceptual overview of performance testing a web based application. The book does a great job of reviewing the ...
An overview of web service testing solutions for traditional or non-technical testers. Much has been written on the technical execution of API tests, yet there are gaps in the details of what tests to design and how to design them. The articles tend to either get too technical too fast, or are too vague and ...
Social APIs are omnipresent and create special cases for testing. If you understand API testing, especially web service type APIs, testing social APIs is easy to grasp. The use of social APIs makes them a special case. They are omnipresent and very well understood. What this means is you need to have a good understanding ...

Leave a Reply

Your email address will not be published.

Stay in the loop with the lastest
software testing news