Blog

- January 27, 2016

DHC is an awesome part of the Restlet platform that facilitates the interaction with RESTful services. It allows you to discover contracts of such services and simulate interactions with them. You’re probably wondering what’s so special about this tool? In fact, it’s a lot of small things that make your user experience better, save you precious time when debugging REST calls, and even sharing your requests with other people.

This article will demonstrate the capabilities of the tool, alongside a variety of convenient tricks for discovering the contract of REST services. Let’s start by installing DHC in your Chrome browser.

Installing the tool

The tool can be used as an online service from https://dhc.restlet.com/ or installed within Chrome from the Chrome Web Store.

dhc-image08

The tool is then available in your Chrome applications through chrome://apps.

Tool overview

DHC provides a workbench structured into three different areas. The following figure provides an overview of these areas and of their aims.

dhc-overview

On the left stands the global area which contains three tabs that give you access to:

  • A list of all the executed requests with a short summary (HTTP method, path and status code of the request).
  • A repository to save and organize your requests. This panel lets you import and export sets of requests. This feature is interesting to share request configurations.
  • Context variables that can be used within request elements.

The right side is divided into two sub panels:

  • The top panel contains the area to define a request, send it and see the response elements.
  • The bottom one provides several tabs containing the global history and other ones related to the current request of the top panel. The HTTP one shows current contents of both request and response as string.

As you probably noticed, the main area is the one regarding the request and the corresponding response. Let’s have a look at how to use it by executing a simple HTTP request.

Executing a first request

Well we will try to interact with a REST service. We have a service called “Contacts Manager” deployed on the APISpark platform but we only have minimal information, i.e. basically URLs of endpoints:

To execute a HTTP request simply set the protocol to use (HTTPS in our case) and the corresponding URL as described below. Let’s start with a GET method to try to get some data.

dhc-simple-request

We can now click on the green “Send” button to send the request and receive the response. When the latter is there, all elements are displayed within the response area.

dhc-simple-response

We can distinguish the status code (200) and associated description (OK), the response headers and the body content. Regarding our response, we can see that the response is correctly executed and we received a response.

We can go further and see the content is a JSON one according to the value of the Content-Type header. DHC detects this and formats this content to be easily readable and more user friendly, in a colorful way. This also makes it possible to see that we received an array of companies with the following structure:

dhc-companies-structure

We can also see that the request was added to both history panels. The first one is located in the left panel and provides a summary of executed requests.

global-history

The second history at the bottom is more detailed and gives additional hints like the request date and its execution time.

history-bottom

We can see the icons describing the status of calls according to assertions. This is related to the testing feature that we will be described in a further article.

If we want to save your request, we can simply need to set a name and use then the save button. A popup is opened to select where to save it. DHC allows to create logical organization at this level with concepts of project, service and scenario.

dhc-save-request

The common approach for RESTful services is to leverage the different HTTP methods they are provided for.

To manage an entity, two different resources are provided:

  • The list resource that manages the entity list with the path /entities/. The GET method returns the list or a sub list according to query parameters and the POST method is responsible for adding an entity in the list.
  • The element resource that manages a particular entity with the path /entities/{entityId}. The entityId parameter corresponds to a path variable that identifies the element in the list. In this case, the GET method returns the data of the element, the PUT and PATCH methods update, respectively fully and partially, the element and the DELETE method removes it from the list.

Let’s try to update data of the service.

Updating data

Before creating a request to add a company, let’s see in more details what can be specified within the request with DHC:

  • The protocol to use to interact with a server.
  • Host and port identify the target to contact to send the request. Once connected to the server, the path is used to select the resource to handle the request.
  • The method corresponds to the HTTP verb used. It identifies the action to execute on the resource.
  • Query parameters are used to build the query string of the request. They contain data that doesn’t fit conveniently into a hierarchical path structure.
  • HTTP Headers define the operating parameters of an HTTP transaction. They correspond to a list of key-value pairs.
  • Request payload corresponds to the data sent when supported. This applies to methods POST, PUT and PATCH only.

Adding an element in a RESTful service corresponds to call a POST HTTP method on the list resource. The first step is to select the POST method in the request area.

dhc-add-company-request1

As this method accepts payload in requests, an area is displayed under the body label to specify content. Previously we saw the format of the ‘company’ element, so we can try to enter JSON data for a new company.

dhc-add-company-request2

Let’s execute this request and have a look at the corresponding response.

dhc-add-company-request3

Boom! Our first attempt failed. The corresponding error message tells us that the provided media type of the response payload isn’t supported. In the context of REST, media type means content type. When sending data, we need to define the structure of the provided data using the Content-Type header.

If we have a look at our request, we can see that we forgot to define this header. DHC allows us to define this in one click simply by using the JSON link below the body area. Sure we could define a new request header by hand by clicking on the + button and fill the two fields, but that’s where DHC rocks. There are always small facilities to make our life easier when using the tool.

dhc-add-company-request4

That should be better. Let’s try again and have another look at the response.

dhc-add-company-request5

We are definitely unlucky but hopefully the RESTful service provides a clear message in the response payload. It appears that the data we sent didn’t follow the right structure. In fact, we made a typo and we need to rename the zipCode attribute to zipcode.

Let’s fix this and try again.

dhc-add-company-request6

Got it! Our company is now added and will appear when requesting the list of companies.

We could use other methods to update or delete specific elements in the list but similar mechanisms will be used.

Defining headers by hand

One of the cool features of REST is the content negotiation (or CONNEG). This allows you to ask the RESTful service for a specific format within the response content. For this we need to leverage the Accept header.

Just click on the + button in the request headers area and start to fill the first input with the name of the header. DHC natively supports auto completion at this level and we can choose the header name in the list. Let’s choose the Accept one.

dhc-add-accept-header

Auto completion is also supported for the header value. DHC detects that the Accept header is waiting for a media type and it proposes a list according to what you have started to enter.

dhc-add-accept-header-value

We can execute our new request and verify that the REST service now returns an XML content for the list of companies.

dhc-simple-request-xml

Another interesting feature of DHC at this level is the ability to disable request headers without having to remove them. This allows you to easily test some combinations. To disable a header, simply uncheck the checkbox in front of the header definition. The line becomes grey.

dhc-simple-request-header-disabled

Now let’s focus on authentication.

Defining authentication

We noticed that there are two endpoints for the service. We made tests with the first one, the company endpoint. Let’s have a go with the contact one.

Following the same method described in the section “Executing a first request”, we won’t receive a 200 status code but a 401 (Unauthorized) informing us that we need to be authenticated to access the resource.

dhc-simple-response-not-authenticated

This means that the resource is secured and we need to send some credentials. Let’s try with HTTP basic authentication. After asking the service provider, I got a username and a password for the service.

These hints must be encoded with Base64 and set within the Authorization header of the response. DHC can help us at this level. Just click on the “set an authorization” link under the request headers label. This opens a dialog window to fill our credentials. Once finished, click on the Set button.

dhc-basic-auth

We can see now that the Authorization header was automatically set by DHC with the right value.

dhc-basic-auth-header

If we execute the request again, we get a successful response.

dhc-get-contacts-request-auth

Content support

DHC also provides advanced support for common contents. Rather than working on raw content, several modes are supported at the payload content level for both request and response levels.

Request payloads

Regarding the request payload, the switch can be done using the combobox at the top right hand corner of the body area.

  • Text content (text value) for formats like raw text, JSON, XML or YAML, with nice syntax highlighting. In this case a text area can be used. DHC provides a set of types right below the text area to directly set the corresponding content type value.

dhc-image22

  • Content from file (file value). In this case, DHC provides an area to drag n’ drop the file or select it explicitly. The tool automatically gets the associated mime type. When clicking on it, the Content-Type header is automatically created.

dhc-image14

  • Forms (form value). DHC supports both simple forms and multipart ones. With simple forms, only text form elements can be defined and the content type is set to application/x-www-form-urlencoded. With multipart forms, you can mix file elements with text ones. In this case, the content type is multipart/form-data.

dhc-image27

Response payload

In the case of structured text, the formatted mode is selected by default to display data using a tree. Raw mode is also available to content as text.

dhc-image07

If no payload is received in the response, the body area remains empty.

dhc-image17

In the case of binary content, several modes are available to preview the content (for examples, see images below) and display it as hexadecimal or raw.

dhc-image26

dhc-image28

dhc-image23

Hypermedia

Another interesting feature of DHC is its support of hypermedia. The tool allows us to leverage hypermedia links within response contents by making them clickable. This way you can follow links to execute other requests very simply. When clicking on a link, a new request is automatically created with the address.

dhc-image18

This also makes it easy to browse RESTful services that use links into their payloads or leverage hypermedia format like HAL, JSON-LD, Collection+JSON to quote a few.

Conclusion

In this article, we described how to leverage the DHC REST client to discover and interact with RESTful services. This tool provides a convenient, consistent and comprehensive interface to define the elements of HTTP requests and display the corresponding responses.

What makes DHC amazing is its ability to guide us when defining requests and providing content, but also to display information. It also provides an interesting way to access other endpoints of RESTful services by automatically creating new requests using links from the responses of your last request.

DHC also provides interesting support to organize requests we made and even export / import them to share them. Testing requests is also a supported feature that we will study in an upcoming article.