# Getting started Welcome to Advanced REST Client application documentation pages. Thank you for choosing Advanced REST Client as you API consumption tool. These pages are your help while working with the application. **If you are still using Chrome plug-in** then proceed to Moving [From Chrome To Desktop Client section](/moving-from-chrome-application-to-desktop-client). The original Chrome application is discontinued as Chrome stopped supporting browser-based applications. ## Project's philosophy ### Open API tooling ARC was built as an open-source and free for everyone API tool out of a passion for giving the developer community tools they need. The application and related projects (like API Console) are created and distributed to our users for free. Our vision is that API tools are available for every developer and organization, regardless of their size, for free and without forced relationship. API tools are using open standards to communicate with other applications so developers can build integrations. ### Community focus Originally the application was created by the author for own convenience while developing APIs. It quickly turned out to be a common problem among developers to consume APIs during the development process. It's because of the community feedback the application grown to offer functionality available to the users today. We encourage you to take part in this project by requesting features, reporting issues, and sharing your use-cases. Discuss ideas in our [ideas portal at GitHub](https://github.com/advanced-rest-client/arc-electron/discussions/categories/ideas). You can check out the current development plan and the road map in our [open project plan](https://github.com/orgs/advanced-rest-client/projects/2). ### Scalability and interoperability The project is developed in a way that allows us to scale the development process by introducing modular and interoperable components to build UIs and application logic. This means that once a feature is introduced into the application it can be re-used in other applications. If you are an API tools developer you are free to take parts of ARC Components and use them in your application. We use open standards when developing the application and not using any particular web framework so we can be sure that each part of the application UI and logic is interoperable. ## Related projects Try other projects that are developed by our team or we think may interest you. * API Console - the API documentation tool - [api-console.io](https://api-console.io/) * RAML - API modeling language - [raml.org](https://raml.org/) * AML - Standards and tools to define, parse and link metadata - [a.ml](https://a.ml/) # Installation ## Installing Advanced REST Client Download the application from [GitHub releases page](https://github.com/advanced-rest-client/arc-electron/releases). In the **Assets** section find the installed that corresponds to your operating system. Windows users should download `arc-setup.exe` file, mac OS users should download the `arc-x.x.x.dmg` file where `x.x.x` is the version number. Linux users can download one of the binaries available for their operating system. ![Assets section for a release](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LgJatkcRkAlPN0u9UJw%2F-LgJc2RSXd58vulIXCe2%2Fimage.png?alt=media\&token=ae2e7dd3-9b0a-4409-9c33-05e164ffa611) {% hint style="info" %} Version number may be different from the one in the screenshot. For normal use, please, download the latest stable version. {% endhint %} When downloaded, run the file. The installer will walk you through the installation process. ## Linux installation ARC's build process generates several builds for Linux. Find your platform and then architecture. Wrong architecture (x86 instead of x64) will result in an error when installing or running the application. Please note that ARC won't update automatically on Linux platform as this is not yet supported by the build library. This may be possible in the future. # Moving From Chrome Application To Desktop Client Advanced REST Client Chrome application is different from its desktop counterpart. This page describes how to move from deprecated Chrome application to desktop client. ## Introduction video {% embed url="" %} Introduction video for moving data to the desktop client {% endembed %} ## Step 1: Install the desktop client Go to to install the latest version of Advanced REST Client if you haven't already. ## Step 2: Export data from Chrome application Open Chrome application. You can recognize it by a green banner in the left-bottom corner saying "**Install new ARC with new features!**" In the top-right application menu, select Import and export data. ![Chrome application menu](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-Lrv9HcRJDxPjAMCEKnX%2Fimage.png?alt=media\&token=27a5ab08-6830-421f-a869-07257ec71b17) Click on the **Prepare data** button to create the export object. Depending on the amount of data it may take a minute or two. ![Export configuration options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-Lrv9hu_xWqmyqi2Qn5o%2Fimage.png?alt=media\&token=9adcd1ea-0f7f-4144-a59b-2c91ad4fed97) On the next screen choose "Download file" tile. {% hint style="warning" %} Do not export to Google Drive as the desktop client don't have access to the data created by Chrome application. {% endhint %} ![Export destination options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-Lrv9vzapbsxMiLS7kRm%2Fimage.png?alt=media\&token=c17a423e-c307-45b1-a7e2-81effa00f451) This opens a dialog to save the file on disk. Select any location to store the file. We will use this file later to import it into the desktop client. ## Step 3: Import data into the desktop client Once the data export from Chrome application is ready, import it to the desktop client. Open Advanced REST Client desktop application. {% hint style="info" %} At this point, your system tells you there are two Advanced REST Client applications installed: Chrome application and desktop client. The desktop client has a different application icon. {% endhint %} Select **File** > **Import data** from the application system menu. ![Import menu option in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-LrvBmF9Zj2S44YmGzZZ%2Fimage.png?alt=media\&token=8f4a3ee9-e885-49a4-a637-7990c5f2af69) In the import screen, choose "Open from file" option and point to the file saved in the previous step. After the data are processed the import inspector screen is rendered. The inspector screen contains a list of all data about to be imported to the application. ![Import data inspector](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-LrvCgTH1JJuchfAeHmQ%2Fimage.png?alt=media\&token=4a241e19-f717-445e-9cc2-99c3b14ddb61) You can ignore some data if you wish. When finished press the "Import data" button at the bottom of the screen. The "Data are now saved in the datastore" message should appear. The data are now moved to the desktop client. ## Step 4: uninstall chrome application Don't get confused by having two applications installed in your system. Uninstall Chrome application using Chrome options. Open the `chrome://apps/` page and find the application in the list of applications. Right-click on the application icon and choose "**Remove from Chrome...**" option. ![Removing ARC from Chrome](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-Lrv7vPaYwiIN2tP3_Vb%2F-LrvDxZv0wWFD5O5wAVt%2Fimage.png?alt=media\&token=d6498f32-c71d-46ad-a361-8be5479e7f9a) That's it. You have successfully migrated from Chrome application to the desktop client. # Privacy About data privacy in ARC The full Privacy statement can be found [here](https://docs.google.com/document/d/1BzrKQ0NxFXuDIe2zMA-0SZBNU0P46MHr4GftZmoLUQU/edit). We do not collect any portion of the HTTP request or a project declaration that can identify data, parameters, or the API. All data are stored locally or on-prem (when the compatible store is configured with the application). On user request, a backup of an HTTP request, API project, or all data can be exported to Google Drive. We do not provide services to store, share, or exchange user data. The application uses the Google Analytics service to provide usage statistics. These data are used to prove the relevance of the project to the stakeholders and to perform usability research used during the design process. Google Analytics is an opt-in option in the application and the user has to actively agree to the data collection. This can be enabled or disabled at any time in the application settings. We are taking steps to ensure none of the user-provided information is transmitted to Google Analytics. **Until version 17** the application was sending a uniquely generated identifier (per application, per user) to the application backend service. This service was recording the most basic usage of the application (number of sessions). This service was removed in version 17. These data were never analyzed nor processed. All data are periodically deleted from the application backend. # Sending requests This guide describes how to make an HTTP request to the API endpoint {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} {% embed url="" %} Introduction video {% endembed %} ## The requests workspace The requests workspace is the main part of the application. It allows you to open multiple requests in a single view. The workspace hosts tabs for the HTTP or web socket editors. To choose between them long-press the add button in the tabs line. ![Requests workspace in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgan9KzZE4YMcXxQfL%2Frequests%20workspace.png?alt=media\&token=33fc69cd-865e-4179-a735-c1e833d34da7) ### Request editor In the request editor, you build the HTTP request to make an API call. You have to provide at least the operation (HTTP method) and the URL of the API resource. The editor also allows you to define HTTP headers and the message body (when applicable to the selected operation). Here you can also define authorization strategy by configuring one of the supported authorization schemes, request actions, and request execution configuration. Finally, you can also generate code snippets for the current request. ### The request URL editor The HTTP request URL is an API endpoint URL you want to perform an operation on. The input field allows you to provide any valid URL data, like, `https://api.domain.com/endpoint?param=value` ![URL editor in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgckLSf76ey07-8ZeC%2Furl-editor.png?alt=media\&token=ac5bcf9e-210e-46f7-9d03-f33f3bfe6982) {% hint style="info" %} The URL is passed to the HTTP client unprocessed to give you more control over request parameters. This means that special characters must be encoded before sending the request. {% endhint %} You can edit query parameters directly in the URL field, but the URL editor has a convenient parameters editor to provide the values and to encode or decode the URL. ![Query parameters editor in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgd64XAilLwVt84Ojx%2Fquery-parameters.png?alt=media\&token=76db25a2-70d1-421c-8484-1d5379cf0ebe) You can disable query parameters. They won't be included in the request, but they can be enabled later when needed. When you see an error indicator in the query parameter this means that the value is invalid per URI scheme specification. Use the **Encode URL** button to fix the problem. ![Query parameters with error indicator](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgeF2Fy6hu8qtLjBkv%2Ferror-query-parameters.png?alt=media\&token=1ee592d5-7c69-4116-8c6b-102d8ed5fc91) {% hint style="info" %} Once encoded value will be encoded again producing an invalid entry. When you want to encode values again, decode the values first and then encode them. {% endhint %} ### API operation (HTTP method) Typical REST operations are: * POST - create a resource * GET - read a resource or a collection of resources * PUT - update a resource by providing a new value to replace the old one * PATH - update a resource with only a part of the resource * DELETE - deletes a resource There are less commonly used methods and Advanced REST Client supports them all but for the purpose of this tutorial we ignore them as probably, you won't use them. ![Operation selector](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTggtCVIZkpccVybrGi%2Foperations.png?alt=media\&token=d82030f7-9751-4564-b350-9416882c8a09) ### HTTP headers The headers are additional meta-information sent to the server to inform it how to process the message. There are well-defined request and response headers like `content-type` or `accept`. Your API, however, may require custom headers. The headers editor allows you to define these headers. {% hint style="info" %} ARC does not generate any request headers with exception of the`Host` header which is required to make a request. Unlike other HTTP clients, only headers that are defined in the editor are sent to the server. This behavior can be configured in the settings. {% endhint %} By default, you see the headers form. Add a header by clicking on the **Add** button. Start typing a header name. The editor renders suggestions if the header name is one of the defined in the specification headers. ![HTTP headers editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTghN0PAas4Vdulv4IA%2Fheaders-editor.png?alt=media\&token=b3e74b25-5d35-49f5-8a24-86211803f4b7) Similar to query parameters, headers can be temporarily disabled to test various options. When the toggle button is unselected then the header value is kept in the editor but it is excluded from the request. You can switch to the text editor to enter the values manually. ![HTTP headers text editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgiP8ov4v9l0pVP8_1%2Fheaders-text-editor.png?alt=media\&token=1d4d9ffc-36fd-43b1-baeb-e43493c5acd8) ### Request body The body is the message you want to send to the server. In RESTful APIs, this is the resource you create or update. ![HTTP body raw editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgiz9esHgXG7kptuCq%2Fbody-raw-editor.png?alt=media\&token=3d39b840-5e55-4401-85e5-31a24ee82685) {% hint style="info" %} GET and HEAD methods cannot define a body on a request. Even though it is technically possible, clients probably won't work with such a request. {% endhint %} {% hint style="info" %} You don't need to set the Content-Length header. It is added automatically when preparing the message. When this header is defined in the headers list it will be used instead. This way you can test your server for invalid input. {% endhint %} The body editor supports syntax highlighting for several content types like JSON and XML. You can switch between different types of body editors. See a related article about editing the body. ### Authorization The authorization editor supports several authorization strategies like basic scheme, OAuth 2, client certificates, and so forth. The authorization configuration is described in the related document. You can use more than a single authorization strategy at the same time. ![Authorization scheme editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgk8-TT3ChKZbNzhw8%2Fauth-selector.png?alt=media\&token=c4280c30-9c97-4b39-aab7-14de001e4db7) When selecting a strategy don't forget to enable it in the selector or otherwise it won't be used with the request. ### Request actions Request actions are the ARC's way to perform some tasks when the request is executed. Actions are executed before and after the request updating your environment. Actions can be conditionally executed, meaning the action runs when a specified condition on the HTTP request data is met. For example, you can check whether a response has the desired status and set a variable from the response body. You can learn more about request actions in the dedicated section. ![Request actions in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTglc_btm7FOW9f_OGt%2Fresponse-actions.png?alt=media\&token=ba8739c2-e598-4f97-9262-015c60f227dd) ### Per request configuration In the request editor, you can set per request configuration options that override the global settings for the HTTP request processing. ![HTTP request execution configuration](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgmQjvizhPhXLVHltQ%2Frequest-configuration.png?alt=media\&token=9f851db4-07b0-49d9-8582-8e385e8968ec) # Body editor This page describes how the body editor works in Advanced REST Client. {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} ## Editing a body in Advanced REST Client ![Raw body editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgmmQkW1K846QmheuK%2Fbody-raw-editor.png?alt=media\&token=ea7fdb7d-0727-4bf4-825b-31ec395ad984) Body editor allows you to define the message body to be sent to the API. You can see the body editor for all operations but `GET` and `HEAD`. While the `HEAD` operation has no message body per the HTTP specification, the `GET` operation is not supported in ARC because all web clients don't support it. The `GET` operation should not carry the body. ### Raw input The row body input allows you to define any text message to be sent with the HTTP request. On the right-hand side of the editor, you can choose one of the popular mime types for the request. This will enable syntax highlighting and syntax validation. ![Mime type selector in the body editor.](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgoaCEgzf3ckqQBc5K%2Fmime-type-selector-body.png?alt=media\&token=b4c22136-2ab2-4230-aed2-d99171ab87aa) By default, the syntax depends on the current `Content-Type` header in the headers editor. When you switch the value in the mime type selector, then the header value is updated. This also works the other way around. When the Content-Type header value changes in the editor the body editor will start using it for syntax highlighting. ### URL from-encoded When the endpoint accepts the `www-url-form-encoded` values, you can use the URL from-enoded editor to build the message. It renders a form of parameters and takes care of the final formatting of the message. ![Form data editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgqPTVOMiiwXbs_guW%2Fwww-form-encoded-form.png?alt=media\&token=36dffbb2-7e08-4593-9f09-f075c16f5953) The final message would be something like the following: ``` client_id=6bf3067f-bc29-41cf-b587-7f3395104fb9&client_secret=ff8c8673-b35b-4c9f-9445-4464a7670e91&grant_type=code ``` Sometimes the name or the value field is highlighted with the error color. This means the entered value is not properly encoded. ![Invalid encoding in the URL form data](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgrFrk0MhY9HJ_V4SY%2Fform-data-error.png?alt=media\&token=b613f1a7-064f-4d7f-80eb-ff95ac8e016b) In this situation simply press the **Encode Values** button to fix this problem. The form names and values are then encoded according to the URI specification. Another time you may see the message: "The content-type header has a different value than www-url-form-encoded." ![Wrong content-type warning message](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgs2OStpavPnkhmO8U%2Fwww-form-data-ct-warning.png?alt=media\&token=c014e8d7-bef0-44a7-87b6-a001af310d80) This warning message is to inform you that you have selected the **www-url-form-encoded** editor but the current value of the **Content-Type** header in the headers editor is different. If you won't fix the problem the server will probably read the message incorrectly or at all. Use the **Fix** button to replace the header value in the headers editor. ### Multipart form data Advanced REST Client has a dedicated multipart form data editor. The multipart body allows you to define a message that is composed of multiple separated parts. Each part has its own message body, encoding, and even file name. When you are testing an API endpoint that accepts the multipart form data message then use this editor to construct your message using the form-based interface. {% hint style="info" %} Current only the `multipart/form-data` is supported. Other `multipart/*` parts are not supported. {% endhint %} ![Multipart Form Data editor in Advanced REST CLient](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgumUC7766GgheRUm5%2Fmultipart-editor.png?alt=media\&token=6c6b7515-e79d-4f17-b835-0f72c5ab7f92) You can define 3 types of form parts. The **file part** allows you to select a file from your local drive and to specify the field name. The application takes care of the formatting of the message. The **text part** allows you to define a plain-text part of the message. In this part editor, when you specify the mime value, it will become the **formatted text part**. The value of this part is sent with the specified mime. You don't need to specify the "boundary" of the content-type header. The application will generate one for you when the final message is generated. The final content header can be something similar to the following: ``` Content-Type: multipart/form-data; boundary=--------------------------292966947351569754674996 ``` ### File editor The file editor allows you to select any file from your local drive and send it with the HTTP message. The file can be any file. You can even send a JSON file like this and the sent message will have the JSON content as it would be read from the "raw" editor. ![File body editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgxHcS8M3j5YwGBqQy%2Ffile-editor.png?alt=media\&token=9ae272c6-0554-4377-98cf-cd4f58d19d80) When a request is sent a proper Content-Type header is inserted according to the file mime type. ### Switching between editors Each editor saves its own state. This means that when you switch from one editor to another the previously set value is restored and the HTTP body value is the one restored from the editor's state. This is a different behavior compared to previous versions of ARC where different editors were trying to use the same values. This was potentially leading to a data loss. Because of that, the behavior changed. # Authorizing a request A walk-through the authorization options in Advanced REST Client. Most APIs require some form of authentication. The most popular and successful authorization schemes are based on adding the `authorization` header with the authorization value. The most commonly used scheme is OAuth2 which uses a Bearer token containing user credentials. This section describes authorization options available in the Advanced REST Client. ## Authorization editor The authorization editor allows you to enable multiple authorization strategies. Each strategy can be configured with the values required in the authorization scheme. For example, the basic authorization requires providing a user name and optional password. ![Authorization editor in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTgYYOt9tjhaa7x7fKO%2F-MTgk8-TT3ChKZbNzhw8%2Fauth-selector.png?alt=media\&token=c4280c30-9c97-4b39-aab7-14de001e4db7) In the authorization scheme drop-down list you can select the authorization scheme you want to edit. In the list, you can also enable and disable the authorization. {% hint style="info" %} Always enable the authorization scheme you edit to make sure it is used during the request. {% endhint %} ### Basic authentication The basic authorization scheme requires the user to provide at least the username. Password is optional. This scheme is rarely used in production systems, but sometimes it can be found in internal systems and the development environment. ![Basic authentication options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThL8rUpowmBOHi-RB7%2Fbasic-auth.png?alt=media\&token=239d2802-b744-4432-bbcc-30d4f9b992db) The authorization header is constructed when the request is being made. The request engine serializes the generated value into the `authorization` header. ### Bearer authentication The bearer authentication was developed as part of the OAuth 2 authorization scheme. This editor allows you to enter a received from an authentication service the bearer token. The application adds the corresponding value to the authorization header. ![Bearer token authentication options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThMbPfwqDWdDaY2OJU%2Fbearer%20token%20auth.png?alt=media\&token=9c0d2713-0a0a-413e-8bc9-50fca5aa2ea1) The value is masked by default for added security. You can preview the value with the toggle button in the input field. ### NTLM authentication The NTLM authentication is used in Microsoft NT domains. It requires making a series of requests with a challenge and responses. After the authorization succeeds then a proper authorization header is added to the request. Because all of this happens on the same connection, the support for it is built into the transport mechanism of the ARC's request engine. ![NTLM authentication options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThNlPhJ8oy-q0fMOzC%2Fntlm-auth.png?alt=media\&token=75514e4a-7db5-4fa7-8331-f642072c2a9a) ### OAuth 1 We dropped support for OAuth 1 authentication scheme in ARC version 16. ### OAuth 2 OAuth 2 is arguably the most successful authentication scheme out there. It allows requesting the authentication token from the authentication server (bearer token). ARC supports all default grant types specified in the OAuth 2 specification. Usually, you have to provide at least the client id parameter you receive from the client registration process. Then depending on the selected grant type, you may need to add other values. #### Implicit grant type (access token) The implicit grant type allows you to request a token without a server component. It also does not require providing the client secret parameter, making it a great fit for web applications without a server component (like ARC itself). {% hint style="danger" %} The implicit grant type is not considered safe anymore. Clients should use different grant types like code with PKCE extension. {% endhint %} ![Implicit authentication scheme](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FSKO3Rx81ouzofHQXrB9L%2Fimage.png?alt=media\&token=f1301894-7c39-457d-8770-c2e8732c8fc6) In this grant type, you have to provide the **client id** and the **authorization URI** parameters. You can optionally include the **scope** parameter. The client id is received from the client registration page of the authentication server. You can find the authorization URI in the authentication provider's documentation. To add a scope to the request, enter the scope value into the scopes' input filed and press Enter or the add button inside the field. The redirect URI must be registered in the authentication server. ARC gives you a default redirect URI you can use. You can also change the redirect URI in the application settings or in the request editor by clicking on the pencil icon next to the redirect URI label. When ready press the **Request Access Token** button to initialize the authentication flow. This will open a popup set in the Authorization URI filed with OAuth 2 parameters computed from the parameters. ARC generates the **state parameter** automatically. Once the token is received, it is visible in the editor. ![Received authentication token](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThT4WbTZyNvxl6Wsw8%2Fimplicit-with-token.png?alt=media\&token=126c2240-9f32-4415-9293-88d6b9b3f503) {% hint style="info" %} You don't need to request the token in the editor. This is to test the configuration. When the token is not set, the authentication process starts automatically when you send the request. {% endhint %} #### Authorization Code grant type It works the same way as the implicit flow, but the popup does not return the token but a code that has to be exchanged for the token. To do this, two additional parameters are required: **client secret** and **access token URI**. ![Authorization code authentication scheme](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThU61huOxb4LF3gCKT%2Fcode-grant-type.png?alt=media\&token=07a4381c-c3cd-4d1e-ab08-77bce08c0cb7) The **client secret**, similarly to the client id, can be read from the client registration page. It is usually a random string of characters. The **access token URI**, similarly to the authorization URI, can be found in the provider's documentation. The **use PKCE extension** option instructs the authentication library to enable PKCE extension when requesting the token in the code exchange process. It adds additional security, but it has to be supported by the authentication server. #### Client credentials grant type. With this scheme, you don't have to provide the authorization URI as this type can be performed without user interaction. The client id and secret are optional. ![Client credentials authentication scheme](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThVd-aLAmswEayMG_R%2Fclient-credentials.png?alt=media\&token=41fd0279-bd84-49a3-9096-a9c2930542f5) The credentials location drop-down allows you to configure where the client id and the secret should be placed. It can be the body with the rest of the parameters or in the authorization header. This should be noted in the authorization provider's documentation. #### Password grant type {% hint style="danger" %} The password grant type is not considered safe anymore. Clients should use different grant types like code with PKCE extension. {% endhint %} The password grant type is similar to the client credentials, but it requires you to provide the username and password. ![Password authentication scheme](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThWdNqNVpSVlM2d85J%2Fpassword-type.png?alt=media\&token=1c1c5192-daf1-4532-a04f-c416105f9939) #### Device Code grant type This grant type is not yet supported. #### Refresh Token This grant type is not yet supported. ### OpenID Connect (OIDC) OIDC is a standard that was built on top of OpenID. Because of that, the UI looks and behaves very similar to the OAuth 2. ![OpenID Connect in ARC](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FpUNw8asKYNZpBmuCdHBV%2Fimage.png?alt=media\&token=af637565-a26d-449f-9ac7-04daf488009b) You start with providing the **issues URI** in the first field. When the value changes the application download the configuration and pre-populates the UI for you. After proving the client ID and/or client secret you can request the token(s). Depending on the selected **Response Type** you can have one or more tokens after the authentication result is ready. \` ![Multiple OIDC tokens in the authorization response](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FTpPWpNYpFLeVHWAUY0l5%2Fimage.png?alt=media\&token=d896ca88-4334-4034-9a9f-aebd42a26e8e) You can select which token you want to use with the request. ### Client certificates The client certificates authentication allows you to select one of the installed inside the application certificates to authenticate the user. The certificates are stored in the application's internal storage, so no one other than ARC can access them. In the first step, you have to import a certificate into the application. ![Import a certificate button](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThXuLubeMqja-QTR_u%2Fimport-cert-auth.png?alt=media\&token=37e48f78-b5d5-468e-b3a0-4bcb98e36781) Press the **import certificate** button or use the Request > Web session > Client certificates menu. The **client certificates manager** screen opens. ![Client certificates manager](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThZ6cVGedfz-usHgu_%2Fcc-mgr.png?alt=media\&token=20d34dd2-940c-4464-8544-f8f403b3d120) Click on the **import a certificate** button. We support the P12 and PEM certificates at the moment. Depending on the type of certificate you have, select the right option for you. ![Selecting client certificate type](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThZbgNGmT0rKODspr-%2Fcc-import-options.png?alt=media\&token=a9458509-a3c1-4a48-8e9e-d2929618ab62) #### PKCS #12 (P12) certificate import ![Importing a P12 certificate](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MTh_LWfPBhD7MN702GA%2Fp12-import.png?alt=media\&token=04547781-7406-44c9-9efc-4c8e283f89d6) Add a name to the certificate. This name is rendered in the certificates manager and the authorization configuration. If your certificate has a password then toggle the **Certificate has password** option and enter the password in the password field. To finish, click the import button. #### PEM certificate import ![PEM certificate import](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MTh_zhS4gAVz7RFFE64%2Fpem-import.png?alt=media\&token=671c68a5-da59-4440-864c-79f134b2c552) To import a PEM certificate, you need the certificate file (public certificate) and the private key. If the private key has a password then toggle the **Private key has password** button and enter the password in the input field. To finish, click the import button. #### Using client certificates Go back to the authorization options. Now you can see there are certificates we imported in the previous steps. ![Selected client certificate](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTh1Qwz9MY5A7EtGVeQ%2F-MThb6_JxEdtdTrucvm2%2Fcc-auth-keys.png?alt=media\&token=87c9adcd-5698-471b-bf04-6da7e507ce97) Now, select the certificate and enable the authentication scheme. The application handles the certificates just before passing the request into the HTTP request processor. # Request editor options Description of the options in the HTTP request editor The HTTP request editor has additional options that can be accessed through the 3-dots icon to the right of the request URL. ![HTTP request editor options](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FNqSs6hoTLscq42Be9j0E%2Fimage.png?alt=media\&token=d67e7a0d-b068-4b81-8077-9d65d98a59de) The **save** option allows storing the current state of the request to the application store. If the request is not already stored. If the HTTP request is already stored this overrides the existing data. ![HTTP request save dialog](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FmNbDwl89uqzEViwZpHiN%2Fimage.png?alt=media\&token=76e5a3c2-0f7f-47b1-ab83-0451d88c4494) The **save as...** option is active when the current HTTP request is already stored in the data store. It opens the "save" dialog and the stored HTTP request is a copy of the current request. The **details** option allows you to view and edit HTTP request details. It has basic information about the HTTP request like type, name, URL, projects it belongs to, and others. ![HTTP request details dialog](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FVYPxYIjBnJRfxSNnK2dD%2Fimage.png?alt=media\&token=8987decd-9f26-4024-b216-cec446d93067) The **Save as HAR** option takes the HTTP request and the latest HTTP response and creates a HAR log with the data exchange. Note, the produced HAR is invalid when the HTTP request has no recorded response. The **Import the cURL command** option allows you to paste a CURL command into the dialog. After confirming the dialog, the contents of the current HTTP request editor is replaced by the values defined in the cURL command. ![](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FbTGs6eGY2FKepWLqDS3j%2Fimage.png?alt=media\&token=81dbbb7d-a788-49b9-8f38-3af5868a2e14) # Environments and variables This guide shows how to use environments and variables in Advanced REST Client. ## The introduction video {% embed url="" %} Environments and variables in ARC {% endembed %} ## Variables overview Variables are used in all request fields (method, URL, headers, body) and allow defining a value in a global scope that is inserted in place when making a request. Environments are the way of organizing variables into a namespace. It allows switching between different sets of variables. It can be used to define variables for a different context like staging and production. Let's say you have "production" and "stage" environments for your API. Both are using different authorization keys. Environments and variables are made to manage a situation like this. Let's say your API supports the `x-client-id` header with some value that is used to recognize the client. Because of the separation of the environments, you have to use different keys for both environments. To deal with this create two environments for "production" and "stage" and create `apiClientId` variables with corresponding values. You can use the variable as `${apiClientId}` in the headers editor as a value. The value is automatically added to the headers before sending the request to the server. ## Listing variables Advanced REST Client lists your application variables created for the current environment and system variables available on your machine. You can use both keys to insert it into a request. ![Variables list](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm0zrcXFx-qir8Qdgc%2Fimage.png?alt=media\&token=79d56fa1-3d06-4fee-9de1-8b8683dea14f) To protect your data variables are masked by default. You can toggle the visibility of the values using the button at the bottom of the variables list. {% hint style="success" %} You can disable application or system variables in application settings. {% endhint %} When switching the environment in the top toolbar you will switch between different application variables defined for this environment. System variables cannot be changed. ![Empty environment](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm1x3YJMKh-yquRTDO%2Fimage.png?alt=media\&token=0f949254-3d3c-4e8f-b8aa-4dd966f31910) ## Editing variables To add a new environment first click on "Edit variables" to open the variables editor. ![Empty variables editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm2B8q9yB5Zvhso9m_%2Fimage.png?alt=media\&token=a566e0a4-6832-4b47-ac8f-0a2b358fa68a) Then "Add" next in the environment selector. It then renders a text field where you can enter a new environment name. There are no limitations for the environment name. ![Adding an environment](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm2YuNwLnHbmCXzEfF%2Fimage.png?alt=media\&token=7e42a3eb-b100-40bb-80cd-50e1a31efe3e) When the environment is saved then you can define variables for it. ![Adding a variable](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm2zrG1XXIXptIBpMB%2Fimage.png?alt=media\&token=b960651e-a738-4270-b3ce-af75c67f3911) You can disable a variable by toggling it on the left-hand side of the input field. {% hint style="danger" %} Variable names must start with a letter and only contain letters and numbers. Special characters or national accents are not supported. {% endhint %} {% hint style="warning" %} The variable value is always visible in the editor mode. {% endhint %} {% hint style="success" %} The variable value can be any value, even another variable. {% endhint %} You can repeat these steps as many times as you need for each of your environments. After your variables are defined you can use them in the editors. ## Applying variables To apply a variable simply as `${` before variable name and `}` after it. ![Applying variable to a request](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm3kq-AFfyBjf_zgkm%2Fimage.png?alt=media\&token=5d1800c3-9b91-4e5e-91fa-08b645156570) The value is applied to the header just before sending the request ![Sent HTTP message with variable applied to a header](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm49LFTIBIJxGou3Zl%2Fimage.png?alt=media\&token=08b6313a-f312-417f-a714-9670ad366015) You can put a variable into a method, URL, headers, or payload field. Variables can be used as many times as you need in a request. ## Composite variables A variable's value can use another variable. Variables make it easier to build variables that require values from multiple sources. As an example, basic authorization requires both username and password. It might be difficult to maintain credentials in multiple requests. It's a better idea to store both the username and the password as separate variables and create a new one that combines both with some additional value. ![Composite variables example](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm7ph7EdsKYTXH66qM%2Fimage.png?alt=media\&token=83369a3d-10f2-44da-93cf-db05396271ab) As a result, the combined value is used with the request. ![Processed variable value](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm84TLxCSfssnTw1u_%2Fimage.png?alt=media\&token=3ed86b76-40de-4c87-aa4c-c786f1440c86) ## Functions in variables You can use one of the predefined functions in your variables. The ARC's engine supports various String, Math, and other functions. To run a function editor press a pencil icon next to the variable value text field. It brings an editor popup with available options with configuration. ![Variable value editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm8osi09ECzwq6doiO%2Fimage.png?alt=media\&token=5d8c2b4c-85cc-4528-8e86-612c31c84133) It uses the JavaScript engine to evaluate the value. We will use a `slice` function from `String` class to demonstrate the principle. The `slice` function accepts two arguments start and end and returns a string that contains characters found between the start index and end index. We are going to "slice" our `${username}` variable to get a string from position 1 to 3. We would use the following syntax: `String.slice(${username}, 1, 3)` where the first argument is the string we are operating on and other arguments are arguments passed to the JavaScript function. In a programming world this would JavaScript would evaluate: `"uname".slice(1, 3)` which result with `na`. ![Evaluated function](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-Lqm9LWi_PaNC5ShmYl2%2Fimage.png?alt=media\&token=878f3c03-8a26-4f71-9fc0-d66a9328d13f) ### Function execution group ARC supports a few additional functions. They are defined in the miscellaneous tab. At the moment you can choose between `now` `random` `decodeURIComponent` and `encodeURIComponent` functions. Now and random functions support grouping that allows you to generate a value once when making a request and to reuse generated value again using the same group name. Pass a value to either of the functions as an argument and re-use the same function call more than once to recall generated value. ![Grouped generated values](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LqlzJjEGyCz9Jci6pdV%2F-LqmCQmbLM8fok-_Hn41%2Fimage.png?alt=media\&token=bd683379-728b-40ad-84aa-75e5c0a59b77) # Host rules This page describes how to use host rules in Advanced REST Client {% hint style="success" %} New in version 17: Read host rules from the OS' hosts file. See below for more details. {% endhint %} ## What are the host rules? Host rules assist your operating system to map a hostname to an IP address. Historically it was used in first computers before the first DNS (Domain Naming System) was created to tell the system what is the IP address of the remote machine while having its name only. Today, it is primarily used to alter host - IP address mapping to something different than DNS tells or to create a mapping that DNS is unaware of. ## Why would you need it in ARC? While developing a web server or an API often the server is run locally or in the local network. In most cases, the IP address, that is well known to you, is enough to run a request. However, sometimes you need to test a configuration that depends on the value of the `host` header. This is quite common for servers that are hosting several virtual hosts. Technically you can manually set the URL to an IP address and then put `host` header in the headers editor to test for virtual hosts. Another option is to alter the system's `hosts` file to create a mapping but this usually requires administrative privileges. In ARC, however, recommended way of doing this is to define custom host rules that map parts of your URL to some other value but keep the original URL to generate a host header when connecting to a server. When you define a rule and the rule matches the URL of the currently executed request, the URL that is used to make a connection is replaced by the mapping value. This way, say, instead of connecting to `host.com` you would be connecting to `127.0.0` (localhost). However, when the HTTP message is constructed, the original URL value is used to set a value for the `host` header which in this example will be `host: host.com` ## Defining rules From the menu Request select Hosts. A host rules mapping screen appears. Click on the add button (right bottom corner of the screen) to add a new entry. ![Empty rule in hosts rules mapping](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWMpqz1d247BzlevvZ%2F-LrWRDvf0tvl5bMzEETP%2Fimage.png?alt=media\&token=d869152e-fe6a-40d5-8887-b39c6e82518a) In the `from` field enter the part of the URL that should be replaced with another value. It doesn't have to be a hostname only. It can be a full URL or a part of it. ![Defining a rule in hosts mapping editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWMpqz1d247BzlevvZ%2F-LrWRjICncS4Jz8zYps1%2Fimage.png?alt=media\&token=8079fa8e-8a1a-459e-89e8-761a808fa407) In this example, the rules mapping maps `https://hosts.com` to `http://127.0.0.1`. Notice that we are not only changing the host but also the scheme. Now you can test whether the mapping meets your expectations by running a request URL through the rules tester. ![Rules tester with result](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWMpqz1d247BzlevvZ%2F-LrWSakrrYeb6BML791e%2Fimage.png?alt=media\&token=6f891b7b-8f4e-4745-b9a3-b51b225ccab2) We are testing `https://host.com/index.html` URL against defined rules. The result shows that the expected result is `http://127.0.0.1/index.html`. Now, we can run a request that uses `host.com` in the URL and the connection is made to the localhost. ![Request made to mapped location](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWMpqz1d247BzlevvZ%2F-LrWTX6bcu1UtcBOz4zW%2Fimage.png?alt=media\&token=b3bf49f4-318d-4881-a0f4-9d98af357fbd) Even though the request URL contains a non-existing URL the request returned data from my locally run server. {% hint style="info" %} All rules are evaluated in order from the first one to the last one. Already altered URL can be altered again by another rule. {% endhint %} ## Examples ### Host-only mapping From: `212.77.100.101` To: `127.0.0.1` This will result in translating the following URL `https://212.77.100.101/index.html` into `https://127.0.0.1/index.html`. ### URI mapping From: `http://domain.com/api` To: `http://127.0.0.1:8081` This will result in translating the following URL `http://domain.com/api/endpoint/?query=something` into `https://127.0.0.1:8081/endpoint/?query=something`. ### With asterisk From: `http://212.77.100.101/*/` To: `http://localhost/path/to/endpoint/` This will result in translating the following URL `http://212.77.100.101/api/whathever/here/test?query=something` into `http://localhost/path/to/endpoint/test?query=something`. ## Reading OS' hosts file Since version 17 you can configure the application to read the operating system's hosts file. These entries are translated into the same data as described above. You won't see the OS' hosts file entries in the host rules editor. They are read each time you send the request. To enable the setting go to the application settings (ctrl/cmd + ,) and scroll to the Request section. Toggle the Read OS' hosts file option. ![Enabled option to read OS' hosts file](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FcCxsigUCwGAFzXEpAngd%2Fimage.png?alt=media\&token=244fbda7-4ee2-42e5-9f24-f36cc3a51a1c) # Request actions This documentation explain what is and how to use request actions in Advanced REST Client. Create request actions to dynamically assign variables when the response from the endpoint is ready. ARC gives you a convenient editor to create actions that are performed each time the request is sent. Actions can be conditional. Create a condition rule for the request action and the action is performed only if all conditions are met. This page describes in detail how to use request actions and conditions. ![Request actions overview](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWUHgmUVpXRAdz6z7W%2F-LrWV5c8Lr-2tFxQLDTN%2Fimage.png?alt=media\&token=ec226b96-0116-4561-89b4-185cfd780fea) There are two groups of actions that can be performed during the request * request actions - executed before the connection is made * response actions - executed when the response is ready ## Request actions Currently request action only allows you to set a value on a variable before the request is made. This value is not stored in the data store but rather in memory only. This means when you restart the application the variable value will be restored to its original value. ![Request action with definition](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWUHgmUVpXRAdz6z7W%2F-LrWW1wjt759YleXilOh%2Fimage.png?alt=media\&token=32661ec2-02f3-4d96-98f8-5b1a5ec80b82) In this example, a `myAccessToken` variable is set to empty string before the request is executed. ## Response action Response actions are more complex as they are made to extract data from the response and assign the value to a variable or store the variable in the data store. The data can be extracted from each part of the request/response parts of the HTTP message: URL, headers, status line, and the payload. ### Extracting the data from the response You need to tell the application where to look for the data that you want to extract from the response. In the editor, you can select either `Request` or `Response` as the main data source. In both cases, the rest of the configuration is the same but it uses either request or response values. The next step is to define what type of data the application should query for the value. It can be `Url`, `Status code`, `Headers` or `Body`. Except for the status code, you should also define the path to the data. Depending on the selected type you can use different paths. #### Path to the data **URL** If you do not specify the path the application will use the whole URL of the last response (it can be more than one response if there was redirection). You can specify the following paths for `url`: * host - Returns the host value, e.g. `api.domain.com` * `protocol` - Returns URL's protocol, e.g. `https:` * `path` - URL's path, e.g. `/path/to/resource.json` * `query` - Returns full query string, e.g. `version=1&page=test` * `query.[any string]` - Returns the value of a query parameter. For `query.version` it would return `1`and for `query.page` the value will be `test`. * `hash` - Returns everything that is after the `#` character, e.g. `access_token=token&state=A6RT7W` * `hast.[any string]` - It treats hash as query parameters and returns the value of the parameter. For `hash.access_token` it would return `token` **Example for URL type** `https://auth.domain.com/auth/oauth-popup?version=2&remember=true#access_token=z8a1d97c-c4e6-488f-8ac0-a32e3d749f49&token_type=bearer&state=Y2I1CD` ```javascript path = 'host' // auth.domain.com path = 'protocol' // https: path = 'path' // /auth/oauth-popup path = 'query' // version=2&remember=true path = 'query.version' // 2 (String!) path = 'hash' // access_token=z8a1d97c-c4e6-488f-8ac0-a32e3d749f49&token_type=bearer&state=Y2I1CD path = 'hash.access_token' // z8a1d97c-c4e6-488f-8ac0-a32e3d749f49 ``` **Headers** Set header name as a path and the value of the header will be extracted from request or response. **Example for headers** ```http Content-Type: application/json Content-Length: 100 Connection: close ``` ```javascript path = 'content-type' // application/json path = 'Content-length' // 100 (String!) path = 'Connection' // close ``` **Body** Currently, only **JSON** and **XML** responses are supported. Also, XML has to be a valid XML string or the parser will not produce the value. For JSON types simply specify the path to the data. To access array value use dot with index notation, for example `data.0.name`. This will get value `name` from the first item of the `data` array. **Example for JSON** ```javascript { property: { otherProperty: { value: 123456 } } } path = 'property.otherProperty.value' // 123456 ``` **Example for JSON array** ```javascript { "data": [{ "name": "a" }, { "name": "b" }] } path = 'data.1.name' // b ``` **XML** Similar for XML: ```javascript const xml = `
202-456-1111 ` path = 'people.person.0.phoneNumber' // 202-456-1111 ``` **Accessing XML attribute value** XML path supports attr(ATTRIBUTE NAME) function that returns the value of the attribute: ``` path = 'people.person.0.name.attr(first)' // george ``` ### Defining the resulting action When `path` is set you can define two actions to be performed on the data. You can either permanently `Store variable` in the application's internal database or `Assign variable` temporarily until you restart the application. The last item is to define a variable name that will be updated with the value. ![Response action definition](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWUHgmUVpXRAdz6z7W%2F-LrWb5obtbLoylmmFGA7%2Fimage.png?alt=media\&token=e265b484-4297-476e-8332-2e9d63d4a3c5) ## Conditions ![](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWUHgmUVpXRAdz6z7W%2F-LrWb_xX4A0rWJp6FnNl%2Fimage.png?alt=media\&token=945f3b39-3bd6-4428-857d-9f33b1c7b688) You can add a condition to the action so the action will be executed if all defined conditions are met. To add a condition to the action click on the `Add condition` button. Source, Type, and Path to data work the same way as in Action editor. After you define the source of the data choose the operator to be used to compare the data. It can be one of: * equal * not-equal * greater-than * greater-than-equal * less-than * less-than-equal * contains Contains can operate on strings, whole headers object (contains "content-type") and on JSON objects (contains "property"). The last field to set up is `Condition value` which is used to compare the data. ## Further reading See our guide to [authorize the application with OAuth 2 and request actions](/guides/authenticating-with-oauth2-and-request-actions). # Cookies and session management Cookies are an important part of the session mechanism in the web and when working with APIs. This section describes how to use cookie manager to authenticate the request using cookies. ## Introduction video {% embed url="" %} Session management introduction video {% endembed %} {% hint style="warning" %} When possible, use other means to authenticate a request like Bearer token with JWT. {% endhint %} Advanced REST Client emulates browser behavior when it comes to handling cookies. When a `set-cookie` header is received as a response to an API call then the value of the cookie is processed according to [HTTP State Management Mechanism](https://tools.ietf.org/html/rfc6265) specification. When a request is made to the cookie domain after the cookie was received it is automatically added to the request. {% hint style="info" %} The "set-cookie" header tells the client (web browser, ARC) that the server requests to store some data on the client. This data should be then sent back with any following request that matches the set domain and path. {% endhint %} ARC is a web-based application and it has a browser included in it. To leverage this ARC allows you to open a Chromium browser window (it is an open-source version of Chrome), log in to a web service, and store received this way cookies into ARC storage. The window opened in ARC has a separate storage and session management than any other ARC window (main application, menu popup window, task manager, and so on). This way you can securely authenticate in the window and only incoming cookies are sent back to the application ignoring any other stored values. ## Authenticating to a web service To obtain and store cookies by logging in to a web service using a browser window select Request > Web Session > Login to a web service menu option. This opens an URL input where you can put the login page URL. ![Login to a web service URL input](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruPVEnpDDEvkH2bjLn%2Fimage.png?alt=media\&token=2735d3f1-3cf5-463c-92a6-6862157073fa) In this example we will use MuleSoft's Anypoint platform login scheme. The login page is accessible under `https://anypoint.mulesoft.com` URL. ![Login page to Anypoint platform](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruSoCyYmZCWnBW9IV4%2Fimage.png?alt=media\&token=4405ac93-5ad7-42e1-9ad3-cdda4eeb1061) After a successful login, a regular page is rendered. ![Authorized user view](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruT1vHkGtcn3YwR-VK%2Fimage.png?alt=media\&token=830e8b75-b8cb-45f5-9b4b-229a6823fe9b) Now the login window can be closed. All cookies sent by the authorization server are now synchronized with ARC's cookies manager. You can see the cookies by selecting the Request > Web session > Cookie Manager menu option. ![Cookies set by the web service](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruUEEOxtpufF4iWBsI%2Fimage.png?alt=media\&token=b9df35bb-277a-4b37-a034-e96f348a17af) When a request to a matching domain is executed the cookies are automatically added to the request. ![Request with cookies added automatically](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruVMNDCEoDPf4SK3Vi%2Fimage.png?alt=media\&token=5d5d512d-4a5a-4511-9255-46aee6e977ac) ## Creating cookies manually In Cookie manager (Request > Web session > Cookie manager) you have an option to create a cookie manually or to edit existing cookie. I am going to create a new cookie that is going to be set to a request send to `domain.com.` ![Cookie editor with values](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruWBgpiJ9JCXNmgELe%2Fimage.png?alt=media\&token=7437f4f7-b4ae-43f6-a7bf-0fee193dfdbb) After saving the cookie a new entry is added to the list of cookies. ![Created cookie on the list of cookies](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruWPS5qClkiisOxj6X%2Fimage.png?alt=media\&token=da992216-614c-4616-a043-305fd194929a) You can preview cookie details or edit the cookie after pressing the "details" button next to the cookie name. ![Cookie details](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruWfUw_Rolb6k1dKg-%2Fimage.png?alt=media\&token=1b909db9-a908-469c-9d92-36a20c5c52e0) After a cookie is set it will be automatically added to a request that matches the domain `domain.com`. ![Request with cookie](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LruKPIWI-y6HVpA2M14%2F-LruX0bNftrhIoVR5MUX%2Fimage.png?alt=media\&token=00c5f293-9086-41b1-a85d-e2fa26f08f9a) {% hint style="info" %} Because the cookie was created with dot "." in front of the cookie domain, the cookie is applied to all requests sent to the domain and all its subdomains. This means the request to the domain `http://www.domain.com` will also have the cookie applied to it. {% endhint %} # Workspaces This pages describes how to use workspaces in Advanced REST Client ## Introducing workspaces {% hint style="info" %} Workspaces are available in ARC 14 and above {% endhint %} A workspace is the current state of the request editors opened in the application. ![Workspace area in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAUWWLCAMaBNOENJh0%2Fworspace-area.png?alt=media\&token=50ce1491-a3e7-4c15-85ec-b3f84c46d0d7) Every time a request property is changed or a response is ready a new state is stored by the application automatically in a file. Request property can be the method, URL, headers, or the payload but also Actions and request configuration. Historically this data was stored in a file in application home directory. Now, however, you have an option to save the workspace state to some other file you select. This file can be later opened by ARC and it restores the same sate. ## Why to use workspaces? When you creating a tutorial or a documentation for your API you can create a workspace that contains all required configuration to run requests one-by-one. You can design the workspace as each tab represent next step in your tutorial. The workspace also contains configuration data like variables and application configuration that should be applied to a request when executing it. ## Using workspaces ### Prepare your workspace To start with a workspace just create a sequence of requests you want to share with your audience. It's just like regular use of ARC. You can design request actions and configure request behavior in the corresponding tabs of the request editor. If you make a request and the response is ready then the response is also added to the current state. {% hint style="warning" %} ARC 14 does not allow to define workspace variables in application interface. Variables can be added by editing generated file. {% endhint %} When ready go to Workspace menu and select Open workspace details. ![Opening workspace details](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAXq07ZjKE0m0h7lze%2Fimage.png?alt=media\&token=e0498b81-67b3-4856-a60f-db09a22abb34) This opens a dialog that shows workspace metadata like description, version, and author information. Don't worry about not having any data just yet. ![Empty workspace details](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAYHmQMSFtNlK-Eq8e%2Fimage.png?alt=media\&token=4968ca96-57a2-4f78-89ba-feb6a42f3a08) The workspace details are for the target audience that gives additional context to the data included into the workspace. Remember, however, that this step is optional. Go ahead and click "Edit" button. It opens workspace details editor that allows you to enter the corresponding values. All input fields are optional. {% hint style="info" %} The description field supports markdown. {% endhint %} After filling the form the preview shows updated information instead "No data". ![](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAZTCLx3s3cmMaARfm%2Fimage.png?alt=media\&token=aa42dbdf-894f-4abd-97eb-0feb928bc1a9) ### Saving the workspace From the *Workspace* menu select *Save as...* option. ![Woskace save as menu option](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAZz5sp_dAAGKYfz5t%2Fimage.png?alt=media\&token=ae16bab3-1354-4606-a970-c48531ee2123) This opens a regular save dialog. Select a location where the file should be stored. ![Workspace save as dialog](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuA_Gjh0JAPFpNpmt5W%2Fimage.png?alt=media\&token=76db89db-b13c-4187-9503-f5b6b2124026) That's it. The workspace is now stored in the file you have requested. When you open the file you will see it's just a JSON file with a representation of the state: ![Generated file contents](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAaRb6BkiUaU8lF2_8%2Fimage.png?alt=media\&token=725e4ad9-3d3e-4259-88df-84b510e8aac5) You can change any of the properties in the JSON if needed. However if you make any change in the application UI the state is automatically stored to the file, unless you open other workspace file. ### Opening workspace file From the *Workspace* menu select *Open from file* option. ![Workspace open from file menu option](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LuAPTrK9R7lS81YGGhj%2F-LuAb0_ZkNID-n8wqpoS%2Fimage.png?alt=media\&token=fdc60516-f512-4ed0-8a2c-7697b0d74eea) This opens new ARC window with the same state as stored when the file was saved. # HTTP Requests History This page describes how to work with HTTP requests history in Advanced REST Client {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} By default when you make an HTTP request the application stores the request and the response data in internal history. This allows you quickly recall past requests from the history menu. You can disable history in application settings. ![History menu in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ0680IOrro1_Er0iw%2F-MTZ2P_xy89UPGDQtdt4%2Fimage.png?alt=media\&token=b870b119-c724-490a-9b67-69a7a2cc2858) An entry in the history menu is created once per day per the URL and the operation (HTTP method). This means that if you make a request to an endpoint that has the same URL and HTTP method multiple times then only a single entry in the history is created. After midnight a new entry for that day is created for the same request. ### Drag and drop List items in the history menu can be dragged to the request workspace (to the right of the menu) and dropped in the tabs area. The request is then opened in the place where it was dropped. Additionally, from the history menu, you can drag and drop a request to the "saved" requests menu and to a project. When dropping a request onto the saved list or a project a new request object is created. It has a default name. You can update the name at any time in the request details. ### History menu options Next to the history menu title, you can open the context menu with additional options. ![History menu context actions](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ0680IOrro1_Er0iw%2F-MTZ4KyMyi3G3cewBUYc%2Fimage.png?alt=media\&token=890d2ed7-2166-439e-b2fb-83a72b711c89) The **refresh** action clears the current list and loads the data from the data store. You don't really have to use this option as when a history object is added or removed from the data store, the list automatically updates the list of requests. The **detach** option allows you to open the history menu in a new window separated from the main application window. You can also detach the entire menu to a new window from the menu *Window* > *Popup application menu*. History menu is a simplified view for your convenience. You can open the **All history** screen for additional options. See below for more details. The **export all** option opens the export dialog asking you where to store the data. Currently, only save to file and save to Google Drive is accepted. After confirming export options it exports all history requests to the selected destination. It is exported as an ARC export object defined as [ExportArcHistoryRequest](https://github.com/advanced-rest-client/arc-types/blob/master/src/dataexport/DataExport.d.ts#L125). The **delete all** options removes all history from the data store. When you select this option a confirmation dialog appears. After you confirm the operation it can't be undone. Make sure to create a backup export before removing the data. ### History screen ![History screen view in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ0680IOrro1_Er0iw%2F-MTZ6N4MoRCO8EbVmKLx%2Fimage.png?alt=media\&token=f4455492-247b-4e5b-b351-a339fb9bb28d) The history screen is an extended version of the history menu. From this screen you can filter history data, select any of them and either export them in the ARC export format or delete them. When deleting data a confirmation dialog is opened. After confirming data removal the operation is final. Make sure you make a backup first. ### Upcoming history features In version 17 (planned release) we plan to utilize the history data collected by the application. The new response view will get a new panel with a list of history responses made to the same endpoint and operation (HTTP method). This was you can inspect how responses were changing in the past. You can discuss the shape of this feature [in this issue report](https://github.com/advanced-rest-client/arc-electron/issues/337). # Saved requests This page describes how to work with Saved requests in Advanced REST Client {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} {% hint style="danger" %} We are planning to remove Saved requests from the application in version 18. All Saved requests that are not a part of a project will be merged into single ARC project. Though, you won't loose your data there will be no option to store a single request in the application. {% endhint %} The concept of a Saved request has been incorporated into the application from its first release in 2011. It allows you to specify an HTTP request object, name it, and store it in a separate data store. A saved request is not a part of a project or an API by default. However, you can add the Saved request to a project. Such a request will be visible in both Saved requests and in the project. From the data perspective a project is just additional metadata over a set of Saved requests (like order, name, and description). ### Saving a request To save a request use one of the following methods: * Focus on the request editor (any part of the HTTP editor) and press `ctrl` + `s` on Windows and Linux or `cmd` + `s` on mac OS for quick save * Focus on the request editor and press `ctrl` + `shift` + `s` on Windows and Linux or `cmd` + `shift` + `s` on mac OS for the "save as.." action * Click on the context menu to the right from the URL editor as select either "Save" or "Save as.." * From the top application menu select *File* and the either *Save* or *Save as..*. #### Quick save The quick save option instantly stores the current state of the request to the data store, when the request is already stored as Saved request. If the request is not yet stored in the data store or if this is a History request then the quick save acts as Save as action. #### Save as The save as action always opens the save request dialog. In this dialog you can add a name to the request, add it to an existing or a new project, and add optional description to the request. ![Save as.. dialog in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ7x5xpa0xdP0hvOj7%2F-MTZCzx8kqAhCMN7DTxO%2Fimage.png?alt=media\&token=845f002f-7873-495b-bb62-9fd4581eae48) After saving a request it is stored in the *Saved menu*. ![Saved requests menu in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ7x5xpa0xdP0hvOj7%2F-MTZDjrQrUWumaRAKfFl%2Fimage.png?alt=media\&token=a2e852b0-f971-4aed-b29b-7cedc05df25f) From this menu you can click on the item to open it in the workspace. If the request is already in the workspace but not visible then this make the request tab visible again. Similarly to the history request, you can drag and drop the request onto the workspace tabs to position the request in a specific place. ### Saved menu options Just like history menu, the Saved menu has context menu next to the title where you can perform additional tasks. ![Context menu in the saved requests](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZ7x5xpa0xdP0hvOj7%2F-MTZEai1I2yunMME_p5N%2Fimage.png?alt=media\&token=301bc774-9296-43be-9a21-f322800efbde) The **refresh** action clears the current list and loads the data from the data store. You don't really have to use this option as when a saved object is changed the list automatically updates the list of requests. The **detach** option allows you to open the saved menu in a new window separated from the main application window. You can also detach the entire menu to a new window from the menu *Window* > *Popup application menu*. The Saved menu is a simplified view for your convenience. You can open the **All Saved** screen for additional options. See below for more details. The **export all** option opens the export dialog asking you where to store the data. Currently, only save to file and save to Google Drive is accepted. After confirming export options it exports all saved requests to selected destination. It is exported as ARC export object defined as [ExportArcSavedRequest](https://github.com/advanced-rest-client/arc-types/blob/master/src/dataexport/DataExport.d.ts#L124). The **delete all** options removes all Saved requests from the data store. When you select this option a confirmation dialog appears. After you confirm the operation it can't be undone. Make sure to create a backup export before removing the data. ### The road map for Saved requests Saved requests planned to be removed in version 18 release (somewhere in the second part of 2021). All requests that are not part of a project will be automatically transferred to a "default" project. You can discuss the planned change in [this ticket](https://github.com/advanced-rest-client/arc-electron/issues/80). # ARC (legacy) projects This page describes how to work with ARC projects. {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} {% hint style="danger" %} We are planning to redesign projects in ARC in the version 18 release. We are still working on the concept of new API projects in ARC. You can join [the discussion here](https://github.com/advanced-rest-client/arc-electron/issues/103) and help us understand your use case for projects. {% endhint %} A project is a set of Saved requests with additional metadata like name and description. Projects allow you to group a number of requests under a single name. It is a similar concept to an API project described in RAML or OAS but without many helpful features of describing an API. Technically requests in a project don't have to share the same base URI. ![Projects menu in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZG7os4EySPxhNcBjv%2F-MTZIXlDCRy_InxUib1z%2Fimage.png?alt=media\&token=80756a00-8b34-4440-8e4a-602a9ec09ea0) The projects menu contains a list of projects stored in the application. You can toggle the list of request in a project by clicking on the project's name. The list of requests behaves similarly to Saved requests. You can drag and drop a request onto the workspace tabs to open the request. You can also drag and drop the entire project onto the workspace tabs to open all requests in the workspace. ### Project context menu When you hover over the project list item an icon appears. When you click on the icon a context menu appears with project context options. ![ARC project's context menu](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZG7os4EySPxhNcBjv%2F-MTZJK50oevt9xGOE4on%2Fimage.png?alt=media\&token=48115858-c649-4817-928f-1a5484afa289) The **Open details** menu option opens the Project details screen. From there you can change project properties and manage requests. When you click on the **Open all in workspace** option then all project requests are being added to the current workspace. The requests are at the end of the current tabs. Similarly, the **Replace all in workspace** opens all project requests in the workspace, but it closes all opened requests. The **Delete project** instantly deletes all requests and the project. Note, that this operation is performed right away when you select this option. Make sure you have backups of your data before deleting any data from the application. ### Project screen ![ARC project screen](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZG7os4EySPxhNcBjv%2F-MTZKuoA4EjY29sIPW4p%2Fimage.png?alt=media\&token=2387073d-5246-4a0f-b3e6-1595ff6e0ca4) The project screen is similar to the Saved requests screen. Additionally, it allows you to open project properties editor and update them. ![Project meta data editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZG7os4EySPxhNcBjv%2F-MTZLGVHSBvreto0T6nF%2Fimage.png?alt=media\&token=0ee34e7a-8aa7-4d41-a734-06e166d0b2cb) ## ARC Projects road map As mentioned at the top of this page projects are planned to be drastically changed. Today this is not how developers work with APIs. It might be convenient was of storing ad-hoc requests but this is not a general use case. We are working on a new concept of API projects. We don't want to add API design capabilities to the application as there are plenty of tools that do it right. We want to focus more on consuming API specifications (RAML, OAS, and AsyncAPI) and help you develop an API with an already designed API. At MuleSoft we offer API design tools and we are looking at ways to connect them with ARC. You can help us decide on future API projects by joining the discussion [in this ticket](https://github.com/advanced-rest-client/arc-electron/issues/103). # Searching for requests This page describes how to search for requests in Advanced REST Client. {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} ![Search results in ARC v16](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZMo1tMCJDiXWULpug%2F-MTZNURm9HITS11rhjnD%2Fimage.png?alt=media\&token=8c63b4db-2cee-45e7-9434-1c2508e4fd9c) Before version 16 search was only possible in the Search and History panels. From version 16 you have a new menu at your disposal to search all requests data in a single place. Currently, it only searches for the saved and history requests. In future releases, we are planning to expand it to more objects stored in the data store. You can search for an URL or its pare like host, path, or even query parameters. Other fields are also indexed, however, they are not indexed for the full-text search. This means that you have to enter the entire word to be matched with the search term. The search result list presents the information about the URL, operation (HTTP method), and request type (Saved or History). For history requests, it shows the time when this request was executed the last time. For saved requests, it shows the name of the request and the names of projects associated with the request. You can click on the list item to open it in the current workspace or drag and drop it onto the workspace tabs to place it in a specific position. # Automated API documentation This document describes how to read API specification (RAML and OAS) to render automated documentation of the API. {% hint style="info" %} This documentation is for ARC version 16 and up. {% endhint %} Advanced REST Client has embedded its sister project developed by MuleSoft: API Console. It is an API documentation tool that generates API documentation from the API model. You can learn more about API Console at [api-console.io](https://api-console.io/). ![REST APIs list in Advanced REST Client](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZPAho85tPZBSjo6jg%2F-MTZPvf7tcrp5RwvMOVS%2Fimage.png?alt=media\&token=f9fa409f-b3a5-4862-a40e-81ec15c7996c) After opening an API specification you can choose to store the API in the internal database for future use. From the REST APIs menu, you can load previously saved API. ![Generated documentation in API Console](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZPAho85tPZBSjo6jg%2F-MTZQRcqaQnrpG4mQdk4%2Fimage.png?alt=media\&token=5ed46cfa-bb92-4373-a665-629e6da99a70) API Console has a different user interface compared to ARC's normal view. It focuses on the documentation part. From here you can learn how the API work but also consume the API through the "Try it" panel. In this editor, the request editor is pre-configured to ask for the request parameters required for the successful connection. Because the parameters are described in the API specification the request editor knows what kind of data to expect. This helps you to faster build the HTTP request and see the result. ![REST APIs context menu](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZPAho85tPZBSjo6jg%2F-MTZRZHdlcSqlfta4UpQ%2Fimage.png?alt=media\&token=6cf04738-8feb-4863-a462-80cdb71c4391) You can choose the **Explore** option from the context menu to find APIs in Anypoint Exchange. It is an API catalog created by MuleSoft. If you have an account and you use our design tools, you can log in to your account to list your private assets. ![](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-MTZPAho85tPZBSjo6jg%2F-MTZRtAbJS2y1GpNgPAo%2Fimage.png?alt=media\&token=bf2338b6-cd4a-427a-bc09-014cc7764da5) When you click on the **Download** button the API specification is downloaded from Anypoint Exchange and processed by ARC to generate the graph model the API Console uses to generate the view. # HTTP Proxy ARC now support HTTP(S) proxy settings. {% hint style="info" %} This documentation is for ARC version 17 and up. {% endhint %} To enable proxy settings go to the application settings (ctrl/cmd + ,) and scroll down to the **Proxy** section. ![Proxy settings section in Application settings](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FZYuMT7MFthJiCL58IRv3%2Fimage.png?alt=media\&token=5bf7d5b8-98b0-4338-a237-26fe03357add) From here you can enable or disable proxy settings. To enable proxying you need to define the proxy URL. It can be an URL or an ID address. After enabling the proxy settings and providing the URL the application will start using the proxy to send the request. **Proxy authentication** Some proxies require authentication. If your proxy needs user credentials, enter the Proxy authentication option in the Proxy settings. This screen allows you to define the username and the password for the proxy. ![Proxy authentication settings](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2F93F60fGfKJRfKYOiReWm%2Fimage.png?alt=media\&token=6335b20c-a195-45b9-855f-3dd9017dec10) **Apply to all application** This option changes the behavior of the application by applying the proxy not only to the requests sent by the request editor but also to all requests outgoing from the application. This includes analytics (when allowed) and application updates (when enabled). **Detect and use system settings** On supported platforms (currently Windows only) it detects the proxy configuration and applies it to the application. When this is set you can skip the configuration of the proxy URL. When the configuration is found it is applied to the outgoing HTTP requests. # Frequently asked questions The most common questions and answers ## The certificate doesn't work In the **Chrome application,** there's little we can do to help. In the **desktop application,** there's a mechanism to manage client certificates. Open the certificates manager from Request > Web Session > Client certificates menu. After adding a certificate to the application internal store you can choose it in the request editor, in the Authorization tab. ## Can I set up a proxy? Version 16 and below do not offer proxy configuration. This was added in version 17. # Application auto update This page describes application updating options. The About screen, which can be accessed from the application menu has the configuration options related to the application updating. ![ARC's about screen](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgJa7u7Cw8HjSR0oUlx%2Fuploads%2FUVfRN8IovLRGQ7s2geaR%2Fimage.png?alt=media\&token=237ff750-faed-4718-a3a9-218786ec6cf3) By default, the application automatically downloads the next stable release of the application and installs it when you close and open the application again. You can control this behavior by toggling the options in the About screen. When you disable the "Automatically download and install updated" the application won't install updates automatically. However, it will check for updates in the background and will notify you about a new version. You will have to install the update manually. You can additionally enable installing of pre-release versions of the application. This will install the so-called beta release. These releases are tested by automated testing services but may not be fully tested by authors or users. Usually, the beta release has new features on which you can give us your feedback. # Authenticating With OAuth2 And Request Actions It becomes challenging for REST testing tools to authenticate the user when the OAuth2 authorization scheme is applied to an API. OAuth 2 is a multi-step process that requires user input, a valid session on the authorization server, and transferring response data from a response to another request. Advanced REST Client has request actions and cookie sessions that allow automating this process so you will spend less time managing sessions and tokens, and do more with APIs. In short summary, OAuth2 requires you to have a valid session on the authentication server, then you have to obtain an authorization token using one of predefined or custom authorization methods (token grant type). The token must be used in an HTTP request that requires authenticated user, usually by putting it into the *Authorization* header (*access\_token* query parameter is also used instead of the header). This article focuses on obtaining an implicit grant type token (I am calling it browser flow because it doesn’t require a server component and is designed to work in browsers only) and then using the token in another request without copying/pasting the token all the time. The first thing we need is to set up a session on the authorization server. Without it, the token request end up being redirected to a login page and therefore the ARC would render this page in response instead of getting token value. Let’s say I want to make a query to Anypoint Exchange to list my API assets. Normally I would go to and log in. Then I would browse the asset in Exchange’s UI. But now I would like to query for my REST APIs assets using the API. To do so we have to set up a session inside the ARC application. Open the application and from the application's menu select Request > Web session >Login to a web service. This brings a prompt to enter the URL of the service. ![ARC menu option to log in to a web service](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWd2WqTPow_OL4IIud%2F1.png?alt=media\&token=5d3ea1b8-f2f8-43b9-a6d5-68f08d1e6376) Now we enter Exchange’s URL () and after clicking the “Open” button it will bring a new window, which is Chromium browser, with loaded Exchange UI. Now we navigate to “Log in” page. ![Browser window opened by ARC to setup the session](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWdEQv9eTGxvWdQ8Ej%2F2.png?alt=media\&token=0615d313-ce81-476d-b3c1-419cf9c3becb) After the login process, the window shows the Anypoint platform page but now we are authenticated. ![Authenticated user in browser window](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWdRiVj8IMzMj8scpK%2Fauthenticated-user-anypoint.png?alt=media\&token=a39a4c68-f4bd-452c-9b49-5b8704b68bcf) To confirm we can go to cookie manager in ARC (Request > Web session > Cookie manager) and query cookies by domain mulesoft.com. ![Generated session cookies](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWddT48FaKC4KWW_6F%2Fcookie-manager.png?alt=media\&token=5a9878bf-b994-4305-a59c-576162d45272) To obtain the token we have to call the authorization endpoint. In my case it is `https://anypoint.mulesoft.com/accounts/oauth2/authorize?client_id=AZ8ewU90hIgZMJec&redirect_uri=https%3A%2F%2Fauth.advancedrestclient.com%2Foauth-popup.html&response_type=token`\ The `https://anypoint.mulesoft.com/accounts/oauth2/authorize` is the authorization endpoint. This is where you redirect the user to authenticate with OAuth2. The `client_id` parameter is generated by OAuth2 provider ID when registering an application (here it is not a real client ID, however, this is public information). The `redirect_uri` tells where to redirect the user after login or failure. ARC uses `https://auth.advancedrestclient.com/oauth-popup.html` by default (you can change it in application settings). Finally `response_type` tells the authorization server that this is implicit authentication flow and in response the app expects the token to be set in the redirect URL. Usually, the `scope` parameter is used with OAuth2 request but I will skip it this time. After providing this URL to ARC’s URL field and executing the request instead of receiving the login page you will see the `redirect_uri` page (the OAuth popup). What is more interesting, the redirect URL contains the `access_token` value in the URL hash part (you may need to toggle “Details” on response view). ![Response with access token](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWeJgkbOSPBdCYlL8I%2Fauthentication-response.png?alt=media\&token=1ec71498-1582-4339-af1e-5f0582bd80c6) Now we have to extract the access token value and put it into an application variable so it can be later used by other requests. We will use the request actions panel to do that. In the Actions tab create a new action in the After response section. We will tell ARC to get the access\_token value from the response URL and then store it as the AnypointToken variable. ![Response action configuration](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWeXDp9dsiKBhISy4O%2Fauth-response-action-configuration.png?alt=media\&token=4939f486-8ca1-46a4-8fa2-8c6269e7ef92) The `hash.access_token` value in the “Path to data” field tells to search for the `access_token` parameter in the `hash` part of the response URL. Finally, the configuration tells the application to store the value as the `AnypointToken` variable. Try running the request again. After the response is ready you will see a new variable in the variables preview (right top corner of the app). ![Variables list with new variable](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWeqIBQ3W-qpp-3OoA%2Fvariables-preview.png?alt=media\&token=1fb2a54a-ea46-43a5-a6ff-329161ea0c5f) At this point, we had authenticated the user in the OAuth service and then we had stored the access token value as an application variable. Now we can use the variable to put the token into the `Authorization` header and make an authenticated call to the API endpoint. Let’s try `https://anypoint.mulesoft.com/exchange/api/v1/profile` which returns profile data for the user. The endpoint requires the bearer token obtained before from the authentication server. In the headers panel put `Bearer ${AnypointToken}` as the value for `Authorization` header. ![Using variables in headers editor](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWfD0fIo1zcjYj8_Ci%2Fauth-anypoint-variable.png?alt=media\&token=031f9587-d984-4c07-8813-244c5c0657a2) After calling the endpoint a 200 response is reported back with profile information. ![Authenticated response](https://2300023309-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgJa7u7Cw8HjSR0oUlx%2F-LrWc35CK-QcAwYrSfGm%2F-LrWfM0g8vzE8CpHZl_y%2Fauthenticated-response.png?alt=media\&token=e1423438-7aa4-4e3d-8d44-f4332385bec3) You can use this example for any other OAuth 2 provider. You may need to change authorization parameters like authorization URI, client id, and so on. # Web APIs basics Learn basics of web APIs in our Web APIs school Before we begin, this article mostly focuses on REST APIs and ignores other types. This will be described in separate articles. A web API, or web Application Programming Interface, is a formalized way of how one application talks to another. The web prefix means that the communication is based on HTTP protocol. Because the transport protocol is not relevant at this time you don't have to worry about it. To visualize this, consider having an application on your smartphone that renders a feed of pictures of people you follow. The application, when running on your phone, knows nothing about what others recently posted on their phones. To get the data about other activities the application has to communicate with the server - an application running on a remote machine publicly available over the internet. Without the API the client application (on your phone) wouldn't be able to understand what the server is talking about. It wouldn't even know how to request for latest updates! Web APIs come in handy in such a situation. They allow to define the vocabulary the applications (the client and the server) are using while talking to each other (we will call them schemas or more widely resources), and the syntax (endpoints and methods). On the most basic level you need 2 to 4 ingredients to allow applications to communicate to each other: 1. Endpoint - the location of the resource, 2. Method - sometimes called the verb or an operation, 3. Optional headers that help the recipient to read the message properly 4. Optional body if required (I will explain later) To perform any operation on a resource, whether it is a read or create operation, the endpoint and the method are always required to start communicating with the server. Endpoint tells where the resource is located (the URI or Uniform Resource Identifier). It is a unique address on the internet where the resource exists. The method has a semantic meaning and tells what kind of operation can be performed on the resource. The most basic operations are: * GET - read the resource or a collection of the resource * POST - create a resource * DELETE - remove existing resource * PUT - update an existing resource There are less common methods like PATCH (partial update), OPTIONS (returns response headers without the actual body), and s few more we won't mention here. You can learn more about them in [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). So now just by having the URI and the method you can recognize what kind of operation on which resource can be performed. ## Headers in API communication When it comes to web APIs, its integral part is headers. Headers are pairs of names and values that help the recipient to understand how to process the request. There are a number of standard request and response headers commonly used in communication with remote systems. Because they are an integral part of the HTTP transport, in most cases the headers are automatically filled up for you when executing a request by the underlying framework your application is based on. Such a common header would be `content-length` that telsl the recipient how much body it should expect before finalizing processing the entire message and preparing the response. When working with web APIs you almost never set this header manually. However, the other very common header `content-type` almost always has to be set by you. This header tells the recipient what is the format of the incoming data. It can be JSON, XML, binary data of any form, and many more. You can also define your own set of headers that are only used by your particular API if that's really needed. However, the standard set of the headers usually is enough for the majority of cases. ## Request and response body The most interesting part for you is obviously the body. This is the reason why the API exists in the first place: to exchange information about a resource. The body is the representation of the resource that resists on the server (or client when creating a resource). I am using "representation" because the resource may be represented in more than one form. For example, a Person resource, which is a user in the system, can be represented in JSON and XML format depending on the [accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) header sent with the request. The response body contains the resource shaped by the request. The request may contain parameters (query parameters, headers) that may somehow transform the response. Consider our picture feed application. When requesting a list of the latest pictures (collection of resources) you may ask the server to return 100 latest posts instead of the default 25. Usually, this is done by defining query parameters that are responsible for pagination. Another example would be searching for a specific tag associated with a picture. In this case, the server would return the same collection of resources but the request parameters would be different and would include the search phrase. After receiving the response, the client can do whatever it wants with it. It can be stored in a local data store for offline use or for caching. Then it is rendered to the final user in the application UI (I am purposely not using GUI as this may come in a variety of forms, like spoken communication). ## API specification Small organizations like small start-ups may not formalize an API for their application in any of the available API description languages. However, it doesn't scale and in long run not having an API specification causes a lot of problems, even internally, not only with external developer teams. Larger organizations prefer the design-first approach where an API is first designed and after it meets all requirements then it is implemented. Currently, the most commonly used languages to describe an API are RAML and OAS. Which one you will choose to use it's up to you. However, you should be aware that API description is as important as having an API. The API specification is a formal record of how your API works. It describes schemas (data types) that are used to communicate with the clients and the structure of the API (endpoints and methods). The obvious benefit of having an API specification is that multiple teams can work in parallel on the same API without the actual API being up and running. Because API specification describes the protocol used to communicate between the server and the application the development teams do not always need access to live API. The second reason to have API specification is the ability to use it in a wide range of API tooling that can read API specification and transform it into something else. For example, there are applications that read API specifications and generate automated, but dummy, server responses. It is called a mocking service. It could be used to test client applications before the API is running. Another example of such tooling is automated documentation generation for your API from a such specification. It can be used internally by your teams but also externally by other developers that are using your API. This is only the tip of an iceberg in API tooling. There is a lot of tools that allow you to automate your work by only just having an API specification. # RESTful APIs getting started This page is a starting guide for working with RESTtul APIs ## API An API or Application Programming Interface is a way of how one system talks to another. It is how the Instagram application on your phone talks to the backend server to request data. Without a common interface that both systems understand, (server understands the shape of the data to send and the client understands how to use the data) applications wouldn't be able to talk to each other. ## REST API **RE**presentational **S**tate **T**ransfer is one of the architectures of an API. The REST API is all about a **resource** (some data stored somehow on the server(s)) and the way how this resource is being transferred to/from the client and what operations are permitted on a resource. In RESTful APIs, there are endpoints that provide access to a resource. An **endpoint** is a [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) under which data may or may not exist. An operation that can be performed on an endpoint is the **method**, also sometimes called the verb. There is a list of well-defined methods and each of them has a different semantic meaning. {% hint style="info" %} A method is not defined by REST API but rather by the underlying HTTP protocol. APIs just use those methods to provide a way to get or modify the data on the server. {% endhint %} **POST** method semantically means that this operation creates a new entity (new data). **GET** method means requesting the current state of the data. GET request can be about requesting a list of resources (like getting a list of Instagram posts) or about requesting a single resource (requesting a single Instagram post). **PUT** operation semantically means updating the whole resource with the data that are transmitted in the request message payload. **PATCH** is similar to PUT but it means to update only this part of the resource that is defined in the request payload. Other properties are unchanged. **DELETE** method removes the data from the system. There are more well-defined methods that you can use with your API. Read more about it on [MDN pages](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). ## HTTP Request Each API method can be invoked by making an HTTP (in most cases) connection to a server and by sending the specially prepared message that every HTTP server understands. The core Advanced REST Client role is to provide a UI for you to provide only relevant data to communicate with the server and it takes care of generating a valid HTTP message. It also reads the response from the server and presents it in a meaningful way to you so you don't waste your time decoding HTTP messages. An HTTP message consists of 3 parts: start line, headers, and the message. The value of each part may vary depending on the request method. The **start line** describes the **requests**. It contains the method name, the path to access the resource (the endpoint), and the protocol version. ```http GET /endpoint HTTP/1.1 ``` Optional **headers** part of the message contains a list of meta-information that describes the request or the client. There is a list of predefined request headers that every HTTP server understands. It is also possible to use custom headers but only some servers will understand it. Each line in the headers part of the message represents a single header. A header starts with a name, then the value separator - a colon - and after that the value of the header. An example headers part: ```http Host: httpbin.org Content-Type: application/json user-agent: advanced-rest-client accept: */* content-length: 110459 ``` {% hint style="info" %} Header names are case insensitive per the HTTP specification. Clients have no obligation to transform headers into a specific form. Headers in the example above are valid even though only some of them start with a capital letter. {% endhint %} Each of the headers has a meaning and the server uses the values to properly process the request. Read more about request headers on the [MDN request headers reference](https://developer.mozilla.org/en-US/docs/Glossary/Request_header) page. Optional **payload** or **body** part is the resource or data being transferred to the server. The body part must be separated from the previous part with an empty line. The body can be anything: an image, a text, some other binary data, or a combination of them. {% hint style="danger" %} Technically in some situations, it is possible to add a body part to GET and HEAD messages but most popular clients (including all HTTP clients on the web) disallow setting the body for these two methods. HTTP specification does not specify the body for those requests and there's no default behavior. {% endhint %} Full example of a HTTP message ```http POST /post HTTP/1.1 Host: httpbin.org Content-Type: application/json content-length: 23 { "data": "value" } ``` ## HTTP Response An HTTP response, the one that is sent from the server back to the client, is very similar to the HTTP request. The two differences are that the start line is formatted differently and it has a different set of headers (called [response headers](https://developer.mozilla.org/en-US/docs/Glossary/Response_header)). The start line consists of the HTTP version, status code, and optional status message. ```http HTTP/1.1 200 OK ``` Status code is pre-defined by the HTTP transport specification codes. And so: * codes of group 100 (1xx) are used when a communication protocol is being negotiated; only HTTP client and server cares about this group * codes of group 200 (2xx) indicates a success of the request * codes of group 300 (3xx) indicates a redirect of some sort (resource location changed, there are multiple choices of a response, etc) * codes of group 400 (4xx) indicates client errors (client not authorized, resource does not exists, etc) * codes of group 500 (5xx) indicate server errors Read more about the response status code, with the full list of predefined codes, on [MDN status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) page. The most common status codes are: * **200** - Successful request. If the request method is GET it means that the message part contains requested data * **201** - Created - When a request method was POST it indicates that the data entity has been created * **301** - The resource has been moved permanently to another location (endpoint) * **307** - The resource has been moved temporarily to another location (endpoint) * **401** - Unauthorized access to the resource. It usually means that authorization data are missing, invalid, or expired. * **404** - Resource not found under given URI * **500** - A server encountered a problem that resulted in an exception; the request processing was aborted * **503** - The server is not yet ready to accept connections. ARC shows additional non-standard status code: 0 (zero). It is reported when the application wasn't able to establish a connection to the server. There may be multiple reasons for that but most commonly is either URL is invalid (check hostname spelling) or the server is down. Less common: DNS cannot find the domain or is down. # Introduction ARC actions allows you automate some work before and after request is made. The request actions allow to perform some logic before the connection to the destination URL is made. At this time you can modify the request values by setting up variables or modifying cookies. The actions run before other transformations are made to the request object like applying cookies or variables. The response actions are performed after the response has been completely ready from the connection, the response object has been created, and cookies has been processed. This way you can modify data stored in ARC after a response has been processed. Actions by default runs synchronously. This means that the request is being made after all request actions finish. The same for the response actions. Response is reported after the actions are performed. When it make sense some actions may have configuration option to enable asynchronous processing. When an action fails the request fails. Some actions may have a configuration option to ignore failures and allow to continue the request. # Set variable action Coming soon. # Set cookie action Set cookie action allows you to create a new cookie or to update existing one from the request or the response data. The cookie is stored in Electron's internal cookie storage (ARC is built on the Electron platform which is derivative of the Chromium project). To set a cookie you need to configure cookie name to set, it's URL configuration, and the value. The **name** of the cookie can be any value that is acceptable as a cookie value in HTTP specification. The **URL** of the cookie can be either a request or final response URL or manually configured from a domain and a path. In the Chromium project cookies are internally associated with an URL. This includes the host part of the URL and the path. Final response URL is the URL used to make the last request before receiving non-redirected response (or the first response if redirects are disabled for the request). Finally the data can be extracted from the request or response data.It can be an URL, headers, or the body. Depending whether it's request or response action the source of the data can be either a HTTP method or the status code. # Remove cookie(s) action Coming soon # Git branches ## Branches used in CI There are four main branches used in the automated build process of the application: * main - reflects the sources of the currently published application in the **stable** (latest) channel * beta - reflects the sources of the currently published application in the **beta** channel * alpha - reflects the sources of the currently published application in the **alpha** (dev) channel * develop - the main working branch where a feature branches are merged into The `main`, `beta`, and `alpha` branches have CI scripts that perform a build once a branch is merged with them. They are testing the application (again) and run the `electron-builder` that is configured to build the application for Windows, macOS, and Linux. For the Windows and macOS builds the builder signs the application with configured certificates \*these certificates are provided by MuleSoft). Additionally, the macOS build is notarized with Apple notarization service. ### Development workflow When starting working on a new feature or a fix a new branch is created from the **develop** branch with a meaningful name related to the task, staring with `fix/[fix name]` or `feature/[feature name]`. Once the work is done the branch is merged through a PR with the develop branch. This does not trigger any action. #### Critical big fixes When a critical bug fix is to be released imminently after the application was patched the the flow starts with creating the `fix` branch from the **main** branch. This is required as this branch gets updated the least and has the stable version code base while other branches may include features that are not yet ready to be published. After the work on the fix is ready the branch gets merged to all four main branches through a PR. With each merge the correct application version has to be set manually (ARC has not automatic version bumping logic). After the merge is completed for each branch the application is being released for the corresponding channel. ### Releasing the application When a new version of the application is ready it goes through three stages of the release process. #### Alpha (dev) channel This channel has always a one major version higher than the stable channel. This channel is to test new features. Each time a feature is merged with the develop branch and this feature is ready to be shipped in the alpha channel a PR is made to the alpha branch. Once the branch is merged an automated build is being triggered. #### Beta channel The beta channel has the next major version release candidate after all features for the release are finalized. A PR from the `alpha` branch is being created with the updated version, which is one major version higher than the current stable application version. Once the PR is merged the build script is triggered. #### Stable channel After release candidate from the beta channel is "enough tested" a stable release can be performed. Similarly to other channels, a PR from the `beta` branch is being created. Once merged it triggers the tests and the build process. #### Final release The release process in mostly automated as described above. However the automated publishing script does not actually publish the GitHub release. This is done manually by team members having a right to publish a GitHub release. This involves building a changelog as a release info and finally publishing the prepared binaries. # Architecture Before you start developing the application learn more about the architecture of Advanced REST CLient ARC is built with Electron and web platform technologies. The user interface and most of the application logic is composed of a number of web components. The components are split functionally in the github.com/advanced-rest-client organization. The `arc-electron` repository is a shell application that bundles the components and provides platform (Electron) specific bindings like persistence layer, file system access, update service, and more. You can learn more about the the architecture for salable application in [this Medium article](https://pawelpsztyc.medium.com/composable-applications-with-web-components-ebe5158387be). ## Electron architecture The best place to start is to explore [Electron documentation](https://www.electronjs.org/docs). We won't be repeating their docs. Instead we focus on ARC's specific implementation. ### Custom protocol in the renderer process ARC's UI is built with web component, which are, by the specification, an ECMAScript modules. To run a web module in the renderer process the server (in this case Electron's implementation of it) that serves the modules must return the `application/javascript` content type. Electron doesn't add mime types for files in the application sources. Because of that, modules cannot run natively in an Electron application. Moreover, to import another module in a module it must use relative or absolute paths (staring with `.` or `/`). The industry standard, however, is to point to an NPM module without resolving paths. This results with a different approach in ARC: to use the [protocol handlers](https://www.electronjs.org/docs/api/protocol). The application internally registers a custom scheme (`web-module:`) for loading files. When the file is being loaded the handler resolves the path to the module (in order: `./src/`, `./web_modules/`, and `node_modules` ) and returns the file content with a proper mime type. See `src/io/EsmProtocol.js` for detailed implementation. The page loading process is managed by the `src/io/WindowsManager.js` which takes care of the proper scheme when loading files. ### Node integration For added security the node integration is disabled in the renderer process. To walk around this, ARC registers a `preload` script, which is executed before the window is loaded. This script has full node and file system access. Inside this script we create interfaces and proxies the application uses to run node modules or to communicate with the main (IO) process. All `preload` proxies and interfaces are located in the `src/preload` folder. For example, the `GoogleDriveProxy` class allows to perform few operations like listing application folder, getting a file, or storing a file on Google Drive. This proxy just passes data to the main process which performs the authentication and the actual operation. This creates a security layer so external script loaded in the renderer process don't have access to all APIs. ### The web\_modules directory Instead of resolving paths in a module ARC uses the `@pika/web` project (now it's [snowflake](https://www.snowpack.dev/)) to resolve and cache modules in a very accessible way. This requires additional step of configuring the `package.json` file and the `@pika/web.webDependencies` entry adding each script to the build process. When the `npm i` script runs it also run the `prepare` script that eventually runs `pika-web` CLI tool. In the renderer process we don't point to `node_modules` but directly to the files in the `web_modules` directory. In fact most UI dependencies are installed in the dev dependencies which means they are not included in the final build of the application. ## ARC components The UI and most of the logic is not located in the electron application but in the ARC web components. This is done to enable sharing the UI and the logic with other projects. 99% of the application logic and the UI is located in these components. Depending on which part you want to change you have to find the corresponding component in the ARC's organization. This document will be updated to add more details about the components architecture.