API and Web Service

API (application programming interface) is a list of methods and classes exposed by a programmer to use by other programmers, so eg if you use Twitter or Facebook API in your programs, you can make it cooperate with Twitter and Facebook, and do many useful things. :-)

There are many ways of exposing APIs (JAR files or RMI in Java, .net Assemblies, COM objects, DLL and .H files in C/C++, JSON over HTTP, XML over HTTP, many home-made methods).

Web Services are just yet another way of exposing API, in this case the actual execution of the exposed methods is done not on your computer, but on some other computer on the Internet (on the Web - hence name "WebServices")

What is an API?

An Application Programming Interface (API) at its core is a formal specification that acts as a guaranteed contract between two separate pieces of software

Modern computer systems are generally designed using the ‘layered architecture approach’:

This means that the core functionality of the system is contained within the “business logic” layer as a series of discrete but connected business components. They are responsible for taking information from the various user interfaces (UIs), performing calculations and transactions on the database layer and then presenting the results back to the user interface.

However, in addition to communicating with human beings via the UI layer, computers systems have to be able to communicate directly with each other. For example, your mobile ride sharing application will need to communicate with the mapping service, the traffic and weather services and other specialized applications used by the drivers providing the rides. In the modern, interconnected world, we take for granted that all these different systems can speak to each other seamlessly, in reality that would not be possible without APIs.

How is An API Defined?

As mentioned above, an API at its core is a formal specification that acts as a guaranteed contract between two separate pieces of software. The API provider defines the set of operations, data formats and protocols that it expects, and the consumer of the API (called the client) will use those rules on the understanding that, as long as it follows the rules, the client will always be able to use the API without having to worry about the internals of the API itself:

The importance of APIs is that it lets different organizations create software applications that rely on other application and services without having to constantly update their application when the internals of the dependent applications or services change. As long as the API itself remains stable, the internal implementation can change. This is an important feature of APIs, they consist of a part that doesn’t change – “the interface or contract” that specifies the operations, data formats and behaviors and the implementation that can change as needed.

Dealing with API Changes

So what happens when you want to change an API and expose new functionality? You basically have two choices:

• Change the existing API to reflect the updated version. However, this is called “breaking compatibility” and means that all clients of the API will need to be updated. Sometimes this is necessary but it should be avoided if possible. This is especially true for applications that are widely used and have many applications dependent on them.

• Create a New API Version and Leave the Old API. This is the recommended option where possible. You create a new API to expose the new functionality but leave the old API in place for existing clients. You may need to add a translation layer to ensure the old API behaves exactly the same as before.

API Testing

So now that we have established what an API is and why APIs are critical to modern interconnected, globally distributed applications and services, it is important to understand why API testing is critical.

API testing involves testing the application programming interfaces (APIs) directly and as part of integration testing to determine if they meet expectations for functionality, reliability, performance, and security. Since APIs lack a GUI, API testing is performed at the message layer. API testing is critical for automating testing because APIs now serve as the primary interface to application logic and because GUI tests are difficult to maintain with the short release cycles and frequent changes commonly used with Agile software development and DevOps.

When you release a new version of the system (e.g. changing some of the business components or internal data structures) you need to have a fast, easy to run set of API regression tests that verify that those internal changes did not break the API interfaces and therefore the client applications that rely on the APIs will continue to function as before.

Why is API Testing Important Now?

The move to cloud computing has highlighted the importance of Application Programming Interfaces (APIs). With the rise in cloud applications and interconnect platforms, API testing is a necessity. Many of the services that we use every day rely on hundreds of different interconnected APIs, if any one of them fails then the service will not work!

What Kind of APIs Can I Test?

Over the years, APIs have evolved from simple code libraries that applications could use to run code on the same computer, to remote APIs that can be used to allow code on one computer to call code hosted somewhere else.

Here is a quick list of the more common API technologies that exist in approximate chronological order:

• TCP/IP Sockets

• Remote Procedure Call (RPC)

• Common Object Request Broker Architecture (CORBA)

• Java Remote Method Invocation (RMI) and Enterprise Java Beans (EJBs)

• Microsoft Distributed Component Object Model (DCOM) – also known as ActiveX

• Web Services (SOAP then REST)

When looking at an API testing tool, it is important to understand which API technologies you will be using and how best to test them. Nowadays most APIs you will come across will be of the Web Service variety (either REST or SOAP), but you may come across other technologies such as Java EJBs or Microsoft DCOM/ActiveX DLLs.

Web Service Testing

A Web service is a unit of managed code that can be remotely invoked using HTTP, that is, it can be activated using HTTP requests. So, Web Services allows you to expose the functionality of your existing code over the network. Once it is exposed on the network, other application can use the functionality of your program.

There are two broad classes of web service:

• Simple Object Access Protocol (SOAP)

• REpresentational State Transfer (REST)

Testing SOAP Web Services

SOAP web services make use of the Web Service Definition Language (WSDL) and communicate using HTTP POST requests. They are essentially a serialization of RPC object calls into XML that can then be passed to the web service. The XML passed to the SOAP web services needs to match the format specified in the WSDL.

SOAP web services are fully self-descripting, so most clients do not directly work with the SOAP XML language, but instead use a client-side proxy generator that creates client object representations of the web service (e.g. Java, .NET objects). The web service consumers interact with these language-specific representations of the SOAP web service.

However, when you are testing SOAP services as well as having a nice interface for viewing the provide services and invoking test operations, you need to always have a way to verify the raw SOAP request and response packets being sent in XML:

This feature in particular distinguishes a true SOAP solution from merely a SOAP client library. The former helps you test the service and understand failures, whereas the latter is just a way of making SOAP web service calls more easily from different programming languages.

The following features should be looked for in a SOAP web service testing tool:

• The ability to download a remote Web Service Description Language (WSDL) file and visually inspect all of its functions and data structures.

• There should be a way to graphically create the SOAP request by taking the functions and populating the required parameters and then viewing the response back from the API. It should handle both simple values (called primitives, such as integers, dates, strings) and more complex structured objects (e.g. a new user object)

• There should be a way to see the raw SOAP XML structure for both the sent request and the retrieved response. Ideally there should be a way to see the XML data nicely formatted so that it’s easier to understand the interactions.

• If possible the tool should support the different versions of SOAP (1.0, 1.1, 1.2) and also handle vendor-specific extension such as Microsoft Windows Communication Foundation (WCP) and ASP.NET Web Services (ASMX).

Testing REST Web Services

A RESTful web API (also called a RESTful web service) is a web API implemented using HTTP and REST principles. Unlike SOAP-based web services, there is no "official" standard for RESTful web APIs. This is because REST is an architectural style, unlike SOAP, which is a protocol.

Typically REST web services expose their operations as a series of unique "resources" which correspond to a specific URL. Each of the standard HTTP methods (POST, GET, PUT and DELETE) then maps into the four basic CRUD (Create, Read, Update and Delete) operations on each resource.

REST web services can use different data serialization methods (XML, JSON, RSS, etc.).

Traditionally the format used for REST Web Services was XML. This is partly because it was used extensively in SOAP web services and is therefore familiar, but also when bandwidth is not a limiting factor, it is self-describing, with the fields and data clearly described:

A common format used in web browser based APIs is JSON since it returns the data asJavaScript Object Notation (JSON) object which can be used directly in a web browser since it matches the format used by JavaScript to store arrays and objects. It is also a very compact format, making it ideal for communications on mobile networks with limited bandwidth.

When choosing a tool to perform REST web service testing, you should look for:

• The ability to prototype and preview the HTTP request, with the ability to specify the HTTP headers, body, method and standard HTTP credentials.

• The ability to see the request and response bodies in a variety of formats, including JSON and XML. The best tools offer automated formatters to make the data easier to enter and view.

• The ability to record your actions and generate a programmatic test script that can be executed automatically for regression and API testing. If possible the tools should provide a way to convert the request and responses into software “objects” that make dealing with the data easier.

• If possible, there should be a way to parameterize the REST requests so that you can create generic REST test functions that can be used in the test script in different ways without having to rewrite each time.

Microsoft DCOM/ActiveX Testing

Microsoft's Component Object Model (COM) also known as ActiveX is a standard for communication between separately engineered software components (source). Any object with a COM interface can be created and used remotely:

var doc = new ActiveXObject("Word.Application");

doc.Documents.Open(wordFileName);

Using this approach, any API packaged as a COM or .NET accessible Dynamic Linked Library (DLLs) can be tested natively by testing tools such as Rapise.

Rapise from Inflectra provides support for testing the following different types of DLL API:

• Managed DLLs – written using the .NET Framework, Rapise provides special access classes for testing these APIs.

• Unmanaged DLLs – written using native Intel x86 code, Rapise provides a special DynamicWrapper than makes it easy to access these APIs