# REST Client The REST Client block is designed for executing HTTP requests. It supports the main HTTP request methods, allowing the User to interact with APIs (including RESTful APIs) using: * GET: Retrieving data. * POST: Sending data to create a new resource. * PUT: Updating an existing resource. * DELETE: Deleting a resource. * OPTIONS: Getting information about the supported methods for a specified resource.
It should be noted that the Execute HTTP Request block in Sherpa Designer is deprecated (it is recommended to use the REST Client block instead, as it is more functional). However, since many Users still use the Execute HTTP Request block, the developers have kept it available for backward compatibility.
Users can flexibly configure request headers, add cookies, and pass parameters in the URL. These capabilities can be useful for: * Specifying data formats, such as \`Content-Type\` or \`Accept\`. * Configuring authorization using headers like \`Authorization\`, allowing for OAuth, API keys, or basic authentication. * Passing additional parameters in requests, which can be useful for filtering or sorting data. When using POST and PUT methods, the REST Client allows the User to send data in the request body. It can: * Send data in JSON, XML, or other formats. * Upload files, enabling integration with services that require content transfer (e.g., images or documents). This is especially useful for working with APIs that accept complex data structures. The REST Client block also provides capabilities for: * Configuring timeout: The User can define how long their request will wait for a response from the server before being canceled. * Error handling: By default, the block returns an error if the server responds with a status other than successful (2xx), but the User can configure it to continue performing actions based on error codes. To ensure security or bypass network restrictions, the REST Client block supports the use of proxy servers. The User can configure: * Proxy address, * Port, * Required authorization to access the proxy. This is useful in cases where interaction with an API is only available through specified intermediaries. ### Example Usage: Yandex Speech API Suppose the User wants to convert a .wav audio file to text using the Yandex Speech API. With the REST Client block, this can be done as follows: 1\. Configure the request: URL: \` Method: \`POST\` Headers: Authorization: Api-Key \ Content-Type: application/octet-stream 2\. Data transmission: In the request body, the User will upload the .wav audio file. 3\. Response handling: The User will receive a text result that can be used in the application. ### Example Usage of REST Client with an Array of Fields of Type \`multipart/form-data\` When working with APIs that require sending data in the \`multipart/form-data\` format, it is important to configure the client correctly. This format is often used for file uploads as well as for transmitting form data. Suppose the User has an API that allows them to upload files and send additional text data. For this, it is necessary to use the \`multipart/form-data\` format. For example, let’s say the User wants to send an image and a description of it to the server. Example of filling in the fields of the REST Client block: | Field | Example Filling | Comment | | -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | URL | | Link to the API that accepts uploaded files. | | Request Type | POST | We are sending data to the server, so we use the POST method. | | Encoding | UTF-8 | Standard encoding for web pages. | | Accept Header | application/json | Specify what type of response you expect from the server. | | Parameters | {"description"="Description of the uploaded file"} | Specify additional data you want to send along with the file. | | Headers | {"Authorization"="Bearer YourAccessToken"} | Specify the authorization header. | | Cookies |


| List of cookies, if necessary for the request. If the server requires authorization via cookies, add them here, obtained from the "Get Cookies" block. | | Files | @{"file"="C:\path\to\your\file.jpg"} | Specify the file you want to upload. Use the full path to the file. | | Request Content |


| Do not fill in this field when using \`multipart/form-data\`, as the data is generated automatically. | | Content-Type Header | multipart/form-data | Specify the content type that corresponds to the data being sent. | | Timeout | 30 | Set the timeout in seconds for the server response. | | Result |


| This field will be filled automatically upon request execution. | | Response Code |


| This field will be filled automatically upon request execution. | | Response Headers |


| This field will be filled automatically upon request execution. | | Cookies |


| This field will be filled automatically upon request execution. | | Error Handling Level | Default | Choose the error handling level. By default, errors will be handled. | | Message Level | Default | Choose the message level that will be displayed during block execution. | | Error Text |


| This field will be filled automatically in case of errors. | ### Error Categories Errors that may occur when working with APIs can be divided into several categories: * Network error: Issues with the network, such as no connection, timeouts, and other failures at the transport protocol level. * Client errors (4xx): These are errors related to requests sent to the server. They indicate that something is wrong with the request or parameters. Examples: \`400 Bad Request\`: Invalid request, syntax error. \`401 Unauthorized\`: Access denied, authorization required. \`404 Not Found\`: The requested resource was not found. * Server errors (5xx): These errors indicate problems on the server side. Examples: \`500 Internal Server Error\`: Internal server error, a general error without specification. \`503 Service Unavailable\`: Service temporarily unavailable, may be overloaded or under maintenance. ### Error Handling in the REST Client To effectively work with errors in the REST Client, several methods are provided: * Error handling strategy: Configure the logic for error handling based on the server response status. For example: For 4xx codes, you can notify the user about an invalid request. For 5xx codes, you can implement retry logic with some delays. * Customizing error messages: You can configure and display more understandable messages for users, providing details about the error. This is important for improving usability. Error logging is an important part of debugging and diagnostics. You can set up error logging to: * Record erroneous responses in a file or database for later analysis. * Include additional context information about the error (e.g., request URL, headers, request body) to simplify diagnostics. In cases where a request cannot be completed due to temporary network or server errors: * Set timeouts for requests so they do not hang indefinitely. * Implement a retry mechanism with exponential backoff for temporary errors. For example, if the server is temporarily unavailable (code 503), it makes sense to try to repeat the request after a few seconds. In addition to error handling in code, it is useful to study the structure of standard error codes to understand how they are grouped and what they mean. Using standard codes will help you quickly identify the cause of the problem and resolve it.