Glossary

A

API

Application Programming Interface (API) is the way a computer program interacts with another computer program. It is possible and very common that one computer program uses the services of another computer program, and that they are connected through a network. This is often referred to as Service Oriented Architecture (SOA).

A computer that offers an API is a server, and a program that uses the service is a client. A supplier does not have to know anything about the client. All it needs to do is to answer specific questions that the clients ask.

These services will be released independently of each other. They can be developed using different tools, different languages, and by different teams. There are many differences, but a common denominator is the way they communicate. They offer an API that others may or may not use through a network. Also, a common property is that they do not have a user interface.

A SOAP API is a standardized communication protocol for XML-based message exchange. SOAP can use different protocols like HTTP or JMS. In SOAP, all parameters a server needs to be able to respond should be in a W3C standardized XML format and part of the body in a request.

REST web services encode most parameters in a request URL, instead of an XML. Data is encoded in the URL or as request parameters, where encoding is not standardized by W3C.

Assertion

Assertions are used to validate functionality, usually through messages by comparing parts of the message (or the entire message) to some expected value. Any number of assertions can be added to a test step, each validating some different aspect or content of a response. They are very important for testing at the most basic level. Using assertions, you can verify that you got the expected result. For example, you can verify a proper connection, correct response format, valid data returned, and many other aspects of testing.

For more information, see Verifying Results.

B

C

CRUD HTTP Methods

Most database operations can be described using the CRUD acronym: you Create data, you Read data, you Update, and, finally, you Delete data.

These operations describe the lifecycle of data in a database. RESTful web services map CRUD operations using the HTTP verbs - GET, PUT, POST, PATCH, and DELETE.

A common mapping between CRUD operations and HTTP verbs is:

CRUD operation	HTTP Verb
Create	PUT with a new URL
	POST to a base URL, returning a newly created URL
Read	GET
Update	PUT with an existing URL
	PATCH
Delete	DELETE

Important

The exact behavior varies with the exact RESTful service.

D

E

F

G

H

HTTP Return Codes

With the HTTP protocol, all HTTP verbs return a response code in the form of a number value. For example, code 200 is returned if everything is OK.

There are a number of return codes, which are grouped by types:

Code Group	Description
Informational	Response codes providing server information (Example: 100 means `continue`, indicating that the server is reachable, but there is no result yet). These are not common in RESTful applications.
Success	The client action was successful. (Small exception for 202, which means the request was accepted and is being processed, with the actual result pending).
Redirection	Sends the calling application to some other resource.
Client Error	The request from the client was broken somehow and needs to be fixed.
Server Error	The server has problems.

Example

Return code	Meaning	Example
200	OK	The request has succeeded. Information in the response depends on the request method.
201	Created	The request has been fulfilled and a new resource is created.
202	Accepted	The request has been accepted, processing is not completed.
401	Not authorized	The request requires user authorization.
404	Not found	The server cannot find anything matching the Request-URL. May be temporary or permanent.
500	Internal server error	The server could not fulfill the request due to an unexpected condition.
503	Service unavailable	The server is overloaded or in maintenance.

HTTP Methods

HTTP methods are actions performed on a resource. ReadyAPI supports the following HTTP methods:

Method	Description
GET	Retrieves information from the service.
POST	Sends data to the service.
PUT	Replaces current representations with the content.
DELETE	Removes all current representations in the target URL.
HEAD	Retrieves the status line and header section only from the service.
OPTIONS	Describes the communication options for the target.
TRACE	Performs a loop-back test for the path to the target resource.
PATCH	Updates parts of the resource.
PROPFIND	Retrieves the properties defined for the resource.
LOCK	Creates a lock for the resource.
UNLOCK	Removes a lock from the resource.
COPY	Duplicates the resource.
PURGE	Removes the cached version of the resource.

J

K

L

M

N

O

Overhead

Any handling of service calls involves some amount of overhead – parsing of data, encoding, creation of files, and so on.

Obviously, as the load increases, it becomes more important to bring down overhead as much as possible.

One way of bringing down overhead is to use a less verbose protocol for requests and responses (for example, JSON instead of XML).

Another way would be to eliminate parsing of encoded data. In a RESTful web service, parameters are (mainly) encoded in the call itself, which eliminates the need for separate parsing of data or files (at least for that part of the service).

Since SOAP relies on XML, it tends to have more overhead than REST.

P

Q

R

REST Representation Type

Representations can be of three basic types: REQUEST, RESPONSE, and FAULT.

Type	Description
REQUEST	An entity sent to the target web server from the client.
RESPONSE	An entity sent by the server to the client in response to the request sent by the client earlier.
FAULT	An entity sent by the server to the client that equates to the error.

S

SOAP

Simple Object Access Protocol (SOAP) is an XML-based communication protocol and encoding format for inter-application communication.

A SOAP API is defined as a standardized communication protocol for XML-based message exchange. SOAP can use different protocols like HTTP or JMS.

All parameters, the server needs to be able to respond to, should be in a W3C standardized XML format and should be part of the body in a request.

The current specification is version SOAP 1.2, though version 1.1 is more widespread. SOAP is widely viewed as a backbone to a new generation of cross-platform cross-language distributed computing applications, termed Web Services.

Stateless

When you design your service to be stateless, you are making it treat each new request as an independent event. It does not store sessions and information about connecting clients. If your service is stateless, you do not need to have a specific client to stay connected to a specific server. Instead of a session with multiple steps between a client and a single server, you get multiple pairs of request-response traffic between a client and multiple service instances. With the growth of traffic, you can add service instances and servers to handle the load. It does not matter where a specific client call ends up, since you do not need to keep track of it.

T

U

URL Encoding

URL encoding converts characters into a web-safe format.

V

Versioning

API Versioning means providing multiple versions of the service to different clients.

A web service may serve clients from many different sources. These clients must be able to understand the API. Yet, you want to change and improve the API constantly. This means that a service will have to deal with clients with different specifications and requirements, providing newer functionality for newer clients that can handle it.

The answer to this problem is versioning. This means keeping multiple versions of your service active and letting clients connect to the version that is appropriate for them.

It is recommended to support 3-5 past versions, or any version released within a year, whichever is greater.

W

WADL

Web Application Description Language (WADL) is the REST equivalent to WSDL. An important difference is that the WADL is not required.

A REST based web service (REST Service) may be defined by a WADL descriptor file. It may look like this:

<application XMLns="http://wadl.dev.java.net/2009/02">
<resources base="http://example.com/api">
<resource path="books">
<method name="GET"/>
<resource path="{bookId}">
<param required="true" style="template" name="bookId"/>
<method name="GET"/>
</resource>
</resource>
</resources>
</application>

A WADL definition is similar to WSDL in the way that it defines what you can do. It defines the supported HTTP verbs. In this example, we can see that we are able to get information about books using the HTTP method - GET. We can also notice that there is a required resource that must be part of the request.

For more information, see a W3C standard suggestion.

WSDL

Web Service Definition Language (WSDL) is a W3C web service description language standard for describing SOAP web services, using XML.

It describes network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a specific network protocol and message format to define an endpoint.

Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used for communication, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

See Getting Started with Schema Inference.

A

B

C

Important

D

E

Important

F

G

H

J

Important

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Search results