Features

Basic RESTClient

So if you didn't yet notice, this thing is a HTTP REST debugger 😃. It allows one to craft arbitrary HTTP requests and send them to servers to see what the result will be.

That's the basic principle of it, any other functions (bookmarks, APS token fetcher) are sugar that is only there to enhance the experience.

RESTClient APS is a fork that is designed to be non-intrusive and therefore provides a stock RESTClient experience if user desires so (just set APS mode to disabled, instructions below).

The most basic workflow to send HTTP request would be:

1. Select the request method in [3].
2. Enter the request URL in [4].
3. If you want to include request body (e.g. for POST request), enter the text in [6].
4. Press the main request sending button [5].

The response panel [15], will fill up with data and you can use its tabs [14] to switch between representations.

Another basic RESTClient feature is the ability to add any custom headers you may want to your request. Just select Headers -> Custom Header in the menu [1].

If you are looking for additions to your HTTP debugging stack, I'd highly recommend Fiddler (for cases when you want to capture requests sent by something other than browser extensions).

APS Token Fetching

The core feature of this fork is the ability to automate fetching of APS authentication token to ease the debugging of APS-related issues.

Currently, the only way to do that is to use PA API. The catch here is that the said API has to be accessible from your machine and that is not always the case, because PA network is often complex and multi-level and having and API (that has no proper permissions model and grants highest level of access possible without SSH to anyone who uses it) available from the outside is a huge security risk.

If the API is not available from your own machine, refer to cURL Integration section below to learn of another possibility to fetch token.

There are several types of tokens that RESTClient APS is able to fetch.

All types have their corresponding POA API method and that method, in turn, has its parameters. Here's a rundown of them:

Token Type	PA API method	Parameters
Account[, Subscription]	pem.APS.getAccountToken	account_id subscription_id
Service User[, Subscription]	pem.APS.getUserToken	user_id subscription_id
Application Instance	pem.APS.getApplicationInstanceToken	application_instance_id
Subscription	pem.APS.getSubscriptionToken	subscription_id
Service Template	pem.APS.getServiceTemplateToken	service_template_id

Full description of these and other PA API methods can be found in the corresponding guide.

Token type is chosen via drop-down menu in panel [10] on the left and parameters are entered in the field on the right.

Parameters are typed into a simple text field separated by space. For example, you have selected a type and entered some parameters:

In that case, the request to PA API will contain 1000001 as account_id and 1000002 as subscription_id. If we omit the second parameter, it will be sent as 0.

• Note: When using browser to access an APS screen in Customer CP, user is given a token that is equivalent to one that is attained by sending the request in the picture just above (both parameters need to be adjusted accordingly):

Basically, when you've selected token type and entered the parameters, you need to choose where to send the token fetching request (PA API URL) and specify HTTP authentication credentials in fields [8] and [9] if they are necessary (they are the same crdentials you use on PA login screen in the browser, most of the time, admin user's credentials are used):

img/pa-api-parameters-example.png

• Note: Field [8] will be auto-filled to default value each time hostname in field [4] is updated. On the picture above, the value was auto-filled from http://mn:8080/aps/2/resources/ in field [4].

The last feature of APS panel is APS mode selector [7]. It defines 3 modes of operation for APS functionality of this extension:

• Disabled. Stock RESTClient experience. No APS-Token HTTP header is sent and no token fetching takes place.
• Manual refresh. APS-Token header is sent on every request with value from field [12] (you can paste your own token there as well). Token fetching occurs only upon pressing Refresh Token button [13].
• Refresh every 25 minutes. A timer that tracks token fetching is introduced. Whenever its value reaches 0 (25 minutes expire), upon pressing main Send button [5], a token fetch is performed with currently set parameters and then main HTTP request is sent with that token. This timer is reset (set to 0) each time when:
• Hostname in main URL field [4].
• Different token type is selected in selector [10].
• Parameters are changed in text field [10].

cURL Integration

Another functionality original RESTClient already had and that was expanded by this fork is cURL integration. The basic idea is that user can always get a representation of currently set up HTTP request as a string that represents the corresponding cURL command.

RESTClient APS expands on this idea (since v1.2) by adding this functionality for APS panel (token fetching request) as well. This allows you to fetch token from hosts other than your machine (the ones where PA API is accessible from).

To activate cURL integration, enable it from the Settings menu [2]:

After that, cURL fields [16] and [17] will be shown:

You can use manual refresh buttons (refresh icons next to each fields) to re-construct cURL string from the request that is currently set up. Also, upon pressing main Send button [5], field [16] will be refreshed, same goes for Refresh Token button [13] and field [17].

Strings from these fields can be copied to a shell (e.g. bash) verbatim and executed right away to fire the same request as was set up in RESTClient APS (token fetching cURL string also has a filter which strips useless data and only leaves token):

Bookmarks & History

The other pretty useful features are history and bookmarks. They allow you to save the requests that were issued at some point in time so you can return and re-issue them later. These two features were adjusted to work properly with APS functionality since v1.2.

First let's look at the history feature. Whenever the main Send button [5] is pressed, the Firefox URL bar will be updated with a hash of a current request:

All input fields of the current requests will be saved in an SQLite database (restclient.sqlite in Firefox profile folder) and then, you can use Firefox's native forward/back controls to switch between previously sent requests. Also there are keyboard shortcuts that can be used to switch history entries.

• Note: Switching between requests restores all fields (including APS ones) from an SQLite database. If you make some changes to the current request and then switch to other history entry using forward/back controls, all changes will be lost (as they are preserved only upon pressing the main Send button [5])

Keyboard shortcuts can be used to quickly switch between history entries.

Bookmarking feature can be used to have advanced request saving functionality. To bookmark a request, use the Bookmarks menu in the top menu bar [1] and select Bookmark This Request. A bookmarking window will appear:

Enter the name of this request and press Save at the bottom. Now if you go back to Bookmarks menu and choose Show All Bookmarks, you will be presented with a window containing all the requests you have bookmarked so far with their parameters shown briefly:

Unlike history, bookmarking feature allows you to restore request without looking through all other sent requests and also gives the ability to restore only main parameters (URL, method and body of the request) or the whole parameters (that adds parameters from APS panel).

• Note: Bookmarking and history data sets are separate and you cannot easily restore request that is saved in history using bookmarks (unless you specifically bookmark the request as well). That said, if the RESTClient APS SQLite database is lost, both data sets will be lost without a chance for recovery.

Keyboard Shortcuts

There are several keyboard shortcuts available for the user when working with RESTClient APS.

• Send main request (v1.1)

Pressing CTRL+Enter is the same as pressing the main Send [5] button. Even when the focus is inside request body or URL input fields.

• Switch to ...

• URL field: U

• Request method: M

• Request body: B

• Toggle response representations

• Response Headers: 1

• Response Body (Raw): 2

• Response Body (Highlight): 3

• Response Body (Preview): 4

• Toggle panels

  • APS: ALT+A
  • Request: ALT+Q
  • Response: ALT+S

• History

Arrow-Left is the same as pressing Back in Firefox, and Arrow-Right is Forward.

Auto Updater

Auto updater alerts the user when the official update for RESTClient APS is released. This feature was introduced in version 1.2.

As a reminder, the only trusted source of the RESTClient APS extension is its GitHub repository (the one this wiki is attached to), do not install this extension from any other sources.

RESTClient will periodically check for updates and if the official repository (the one this wiki is attached to) has a new update, several UI elements will change. Updater button will be shown near the Settings menu [2]:

The title of RESTClient tab will also be changed:

When you click the updater button, you will be presented with several links (each opens in a new tab) related to this update:

The fastest way to download new update is to click Download: restclient-aps.xpi, this will download the .xpi file from GitHub and install it with user's confirmation. As usual, you will need to restart Firefox after the installation.

Other Features

• Request Execution Timer. You can enable it in the Settings menu [2]. Then, after you send a request, a small bar at the bottom will show you how long did it take:

• Text Area Auto Resize. After enabling it in the Settings menu [2], request body [6] and cURL fields [16], [17] will be resized automatically when their content changes. Resize handles will be removed:

• Controller URL autofill. If RESTClient APS button is used when the active browser tab contains POA screen, the newly open RESTClient APS screen will have its controller and PA API URL fields pre-filled with values from that tab.