Headers
The REST headers and parameters contain a wealth of information that can help you track down issues when you encounter them. HTTP Headers are an important part of the API request and response as they represent the meta-data associated with the API request and response. Headers carry information for:
- Request and Response Body
- Request Authorization
- Response Caching
- Response Cookies
Other than the above categories HTTP headers also carry a lot of other information around HTTP connection types, proxies etc. Most of these headers are for management of connections between client, server and proxies and do not require explicit validation through testing.
Headers are mostly classified as request headers and response headers, know the major request and response headers. You will have to set the request headers when you are sending the request for testing an API and you will have to set the assertion against the response headers to ensure that right headers are being returned.
The headers that you will encounter the most during API testing are the following, you may need to set values for these or set assertions against these headers to ensure that they convey the right information and everything works fine in the API:
Authorization: Carries credentials containing the authentication information of the client for the resource being requested.
WWW-Authenticate: This is sent by the server if it needs a form of authentication before it can respond with the actual resource being requested. Often sent along with a response code of 401, which means ‘unauthorized’.
Accept-Charset: This is a header which is set with the request and tells the server about which character sets are acceptable by the client.
Content-Type: Indicates the media type (text/html or text/JSON) of the response sent to the client by the server, this will help the client in processing the response body correctly.
Cache-Control: This is the cache policy defined by the server for this response, a cached response can be stored by the client and re-used till the time defined by the Cache-Control header.
Parameters
REST parameters specify the variable parts of your resources: the data that you are working with. As was mentioned in a previous article Understanding REST & SOAP Request Methods, in a REST request the resource that you are working with is specified in the URL – Uniform Resource Locator. The URL is a special case of the URI – Uniform Resource Identifier – which consists of four parts:
scheme_name:hierarchical_part?query#fragment
In the article detailing the SOAP vs. REST debate we discussed that REST is not a standard in itself, but instead makes extensive use the HTTP standard. Therefore for all REST calls, the scheme name will always be “http:”, or “https:” if sent over a secure channel.
RESTful Resources
In any RESTful service it is very desirable to have all your resources structured by their hierarchy. These are then specified in the hierarchical part of the URL. The hierarchical parts are all 1) required, and 2) unique. This means that none of them can be omitted, and all of them can appear only once. Certain parts of the URL are going to be fixed (such as the server name, port, and endpoint), and certain parts are going to be parametrized. The parametrized parts are often denoted in code and in documentation by curly braces.
Consider, for example, a web service for ordering books. Your data might be organized into customers, which contain orders, which in turn contain individual books. The resource URL might look like this:
http://server.test:8080/order_api/{customer_id}/{order_id}/{book_id}
Sending a DELETE request to this URL might remove a book from an existing order, while sending a GET request to this URL might retrieve the details of a particular book (such as if it is on back order or out of stock).
Alternatively, an airline booking engine might structure their data by airplane first, which in turn could contain customers. The URL might look like this:
https://airline.server.test/ticketing_api/{flight_id}/{customer_id}
Note that for an airline the flight (airlines refer to specific flights as a “tail”) is the bigger object they need to keep track of, which then contains customers (passengers). While in the previous example, there is really no object in a bookstore that would contain customers.
SoapUI Open Source
- Support for SOAP and REST API Testing.
- Easy multi-environment switching.
- Detailed test history and test comparison reporting.
SoapUI Pro
- Support for SOAP, REST, and GraphQL API Testing.
- Easy multi-environment switching.
- Detailed test history and test comparison reporting.
Query Parameter
The query parameters are sometimes referred to as optional parameters; this is the first distinguishing feature from the hierarchical parameters: they are all optional. The second feature is that they are non-unique, meaning that you can specify any one parameter multiple times. The query parameters are separated from the hierarchical parameters by the question mark. The exact syntax of the actual parameters is not generically defined, but normally are a sequence of key-value pairs (separated by an equal sign), with the sequence separated by either a semicolon or an ampersand.
Building on the above airline example. A customer, when making a booking, may wish to add options, such as vegetarian meal and wheelchair access. The URL for this resource could look like this:
https://airline.server.test/ticketing_api/{flight_id}/{passenger_id}?option=vegetarian&option=wheelchair
Fragment Parameters
The fragment part of the URL, everything after a hash symbol, is information that is normally used only by the client, such as a browser, and not processed by the server. Therefore it is uninteresting when discussing REST parameters. The only interesting item is if you need to send the actual hash character as a value (instead of representing the hash control symbol) to one of the options. In that case you need to encode the URL.
Character Encoding
Special characters are encoded in the URL, by a mechanism called “percent encoding”. In this mechanism any character can be replaced by the percent symbol, followed by a two-digit hexadecimal value of the encoded character. If special characters (such as the hash character) need to be sent as actual data, they must be encoded. All other characters can optionally be encoded.
Size Limits
Although the URI standard does not specify a maximum size of the URL, most clients enforce an arbitrary limit of 2000 characters. Sending data that is difficult to express in a hierarchical manner, and especially data that is larger than this 2000 character limit, should be transmitted in the body of the request. As was discussed in SOAP vs. REST the data in the body can be structured in any machine readable format, but most often is structured as XML or JSON.
No one knows APIs better than SmartBear. Find out what our Pro version of SoapUI can do to improve your testing.