Lack of information and access to information isn’t an issue with web services. Web service documentation is widely available.
Overview
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.
Guidelines
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
http://en.wikipedia.org/wiki/Application_programming_interface
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:
- a description of all the data structures it depends upon;
- a description of all the functions’ signatures,
including:
function names
- function parameter names (when it applies) and types
- return types for the functions
- for each parameter, whether the parameter is possibly subject to modification inside the function
- a description of the handling of any error condition
- pre- and post-conditions or invariants
- more generally, how the state has changed after the function’s execution
- possible side-effects
- any accessibility or visibility constraint.
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:
https://developers.google.com/android-pay
https://developers.google.com/wallet/objects/
Testing and Test Flows:
https://developers.google.com/android-pay/test-flows
SalesForce
Overview: https://developer.salesforce.com/docs
Developing and Testing with Sandbox:
https://developer.salesforce.com/trailhead/app_deployment/app_deployment_sandbox
