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.
These descriptions and the glossary can be the foundation for further learning on testing web services. The description is compiled from a few sources:
- Sarah Maddox: API types
- Stack Overflow: JSON, REST, SOAP, WSDL, and SOA: How do they all link together
- Eric J. Bruno, Dr Dobbs Magazine:
SOA, Web services, and RESTful Systems
Web service APIs
A web service is a piece of software, or a system, that provides access to its services via a URL. A web service
offers its information in a format that other applications can “understand”, or parse. An application programming interface (API) is a set of routines, data structures, object classes and/or protocols provided by libraries and/or operating system services in order to support the building of applications. All web services are APIs but not all APIs are web services. A web service needs a network, while an API doesn’t need a network for its operation.
Web services use HTTP (or HTTPS) to exchange information with an application, or a “client”, that wants to communicate with the web service. The application sends an HTTP request and the web service then sends an HTTP response (the web service request is sent in a SOAP or REST format; more on this follows).
In the request the required information is passed in the URL itself, as paths in the URL and/or as URL parameters.
For example, the following web service call URL is a request sent to Google Maps and the response will be a map of Syndey, NSW (New South Wales) AU with a specified size and zoom: http://maps.googleapis.com/maps/api/staticmap?center=Sydney,NSW&zoom=14&size=400×400&sensor=false
For all this to work, there’s an interchange mechanism between the back-end (web-service) that does the processing and generation of something useful, and the front-end (which consumes — typically displays — the data), which could be anything: a web, mobile, or desktop application, or another web-service. The only limitation is that the front-end and back-end must “speak” the same “language”.
That’s where SOAP and REST come in. They are structured practices to choose to communicate with the web-service. SOAP, Simple Object Access Protocol, is a specification for exchanging structured information in the implementation of web services in computer networks.
SOAP internally uses XML to send data back and forth. SOAP messages have rigid structure and the response XML then needs to be parsed. WSDL is a specification of what requests can be made, and with which parameters, and what they will return. It is a complete specification of your API.
REST/RESTful is a design concept (the World Wide Web represents the largest implementation of a system
conforming to the REST architectural style) that isn’t as rigid as SOAP. RESTful web-services use standard URIs and methods to make calls to the web service. When you request a URI, it returns the representation of an object, one that you can then perform operations upon (e.g. GET, PUT, POST, DELETE). You are not limited to picking XML to represent data, you can pick anything really (JSON included).
The HTTP query URL definition is all you need to know and use to make calls to a RESTful service. The response can be HTML, comma-delimited data, XML, or a more sophisticated document type (such as a spreadsheet). Some, though, claim that the return of anything but hypermedia-based content is not truly RESTful.
Example: A call to retrieve employment benefits for an employee.
some data here…
JSON and XML
JSON and XML are data representations and are ways of serializing data. XML is more flexible and has quite a few standards designed around it, but some feel it is too complex and verbose. JSON is a simpler format which
defines a few basic structures in concise ways, which is easy to use for informal data structures.
Accessing an API usually requires some kind of authentication through a proxy using API keys, tokens, usernames/passwords or database URLs. An API key is a code passed by computer programs calling an API. It
identifies the calling program, its developer, or its user to the website. API keys are used to track and control how the API is being used, for example to prevent malicious use or abuse of the API.
Basic auth over HTTPS – Check username/password of the user for every request.
Sessions – Send a session ID with each request; server maintains state. So app sends username/password and server checks for a logged in user on subsequent requests, just like any website does.
API tokens – Mobile app sends username/password and receives a token back, then appends this to subsequent requests. Token stored in DB and checked on each request.