REST is a style of software architecture for distributed systems, such as the World Wide Web. Due to its simpler style, over the past few years REST has increasingly displaced other design models such as WSDL and SOAP, and at the same time, has emerged as a predominant Web service design model. A RESTful web service, also known as RESTful web API, is a web service implemented using the HTTP protocol and the principles of REST. It is a group of resources with these defined aspects:
-
The base URI for the web service. This is an example URL: http://example.com/resources/
-
The internet media type of the data is supported by the web service. The most popular are JSON and XML but can be any other valid Internet media type.
-
The set of operations supported by the web service using HTTP methods such as GET, PUT, POST, PATCH, HEAD, OPTIONS, or DELETE.
-
The API must be hypertext driven.
For more information, go to these sites:
-
http://en.wikipedia.org/wiki/Representational_state_transfer
-
http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm#sec_6_1%7C
The EC-Rest plugin calls the RESTful web services using HTTP Requests and passes the user-provided parameters. It is open and allows the input of any HTTP request that is defined in the provided fields of the parameters. You must provide all the parameters required for the correct functioning of the REST Client.
Plugin version 2.3.3.2022101396
Revised on October 18, 2022
Plugin configurations
Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.
Creating plugin configurations
To create plugin configurations in CloudBees CD/RO, complete the following steps:
-
Navigate to .
-
Select Add plugin configuration to create a new configuration.
-
In the New Configuration window, specify a Name for the configuration.
-
Select the Project that the configuration belongs to.
-
Optionally, add a Description for the configuration.
-
Select the appropriate Plugin for the configuration.
-
Configure the parameters per the descriptions below.
Configuration procedure parameters
| Parameter | Description |
|---|---|
Configuration name |
The name for the created configuration. |
Description |
Description of the configuration. |
URL base |
Base URL for rest requests. Example: https://example.com/rest/v1.0 |
Port |
Server port. Leave empty to use default port used for the provided scheme. |
Ignore SSL issues |
Turn SSL verification off for instances with self-signed certificates. |
Auth type |
Authentication type: An anonymous, basic or bearer token. |
Login as |
The credential for basic authentication. |
Bearer Token |
The credential for bearer authentication. |
Authentication header |
The credential for custom authentication header/prefix. e.g.:
|
These fields are going to be used for the checking connection only |
|
Path URL |
Relative URL Path. Used for checking connection. eg.: service |
Content type |
Provide the Content-Type required for the request. Used for checking connection. eg.: text/plain application/json; charset=utf-8 |
Cookie value |
Value that will be sent as a cookie. Used for checking connection. e.g.: 'foo1=bar1;foo2=bar2' |
Headers |
Provide the headers required for the request. Remember to write "Key" whitespace or colon or equal and then "Value", If more than one header, write each header in separate lines. Used for checking connection. eg.: myHeader=myValue header3:third simple_header simple_value |
Form content |
Provide the Content required for the request. Used for checking connection. eg.: {"key" : "value", "tag" : "ttt", "level" : 1} |
Request type |
Select the request type from these options: GET, POST, PUT, PATCH, HEAD or DELETE. Used for checking connection. |
Check Connection? |
If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails. |
Debug level |
This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed. If Trace is selected, all requests and responses are displayed. |
Plugin procedures
runRest
Use this procedure to allow the input of any HTTP request that is defined in the provided fields of the parameters. The plugin analyzes the parameters that were sent and attempts to create and send the HTTP request. After the request is sent, the plugin analyzes the response and the user receives the result, either a success or failure.
runRest parameters
| Parameter | Description |
|---|---|
Configuration name |
The unique name for the configuration. |
Ignore auth |
Procedure will ignore the credential specified in the configuration for this request. |
Path URL |
Relative URL Path. eg.: service |
Content type |
Provide the Content-Type required for the request. For example: text/plain application/json; charset=utf-8 |
Cookie value |
Value that will be sent as a cookie. e.g. 'foo1=bar1;foo2=bar2' |
Headers |
Provide the headers required for the request. Remember to write "Key" whitespace or colon or equal and then "Value", If more than one header, write each header in separate lines. eg.: myHeader=myValue header3:third simple_header simple_value |
Form content |
Provide the Content required for the request. eg.: {"key" : "value", "tag" : "ttt", "level" : 1} |
Source file |
Path to a file that provides the content required for the request. Used instead of "Form Content" eg.: /path/to/text/content.txt |
Request type |
Select the request type from these options: GET, POST, PUT, PATCH, HEAD or DELETE. |
Request timeout |
REST client request timeout in seconds. |
Download to file |
Enables download big content to a file. |
Target file |
Name of the target file for downloading. |
Post script shell |
A shell that will be used to execute the provided script. Can be in form of an absolute file path (e.g. /usr/bin/python) or a shell name (in case it is contained in $PATH environment variable, e.g. ec-perl). |
Post script content |
Script content that is being used for response handling. See Post Script Shell parameter description for additional details. |
Post script output file |
File path, relative or absolute, to store the result of the post process script. If specified, STDOUT of the post script will be saved into this file. If the file name is relative, the file will be saved into the job workspace. |
Response (output property path) |
The property with response body (like "/myJob/resultBody") or path to the target file if "Download to file" is checked. |
Response regular expression for polling |
Regular expression to be evaluated in the response content. If the parameter is provided, request would be performed repeated times until it matches response content or timeout expires. If the parameter is not provided, it is not evaluated. Request would be performed once. eg.: 1\d{10} \d{5}(-\d{\4})? |
Incompatibilities between v1 and v2
After migration from v1 to v2 old configurations became incompatible. All of them should be recreated manually.
Also, procedure runRest uses parameter config instead of connection_config. All calls of the procedure should be updated manually.
ec_setup.pl script from v1 always only add its step picker independently of the context and never removes it. This causes the step picker to have two "runRest" instances after upgrading.
Workaround after upgrade: 1. Uninstall old EC-Rest 2. Delete property "/server/ec_customEditors/pickerStep/Rest - Run Rest" 3. Clear browser’s cache
Use cases and examples
Example 1: GET request with no authentication
One of the most common uses for this plugin is to perform a GET request and retrieve some information from a RESTful Web Service with no authentication required. After the user enters the required information, the plugin creates the request, sends it to the server, and waits for the response. The user receives the result, which is success or failure.
Create a new request by specifying the parameters:
After the parameters are set, you can run the step.
Example 2: POST request with basic authentication
Another common use of the plugin is to perform a POST request and retrieve or change some information on the server. For this example, authentication is required. After the user enters the required information, the plugin creates the request, sends it to the server, and waits for the response. The user receives the result, which is success or failure.
Create a new request by specifying the parameters:
Release notes
EC-Rest 2.2.0
-
Added downloading to a file.
-
Added option "Request timeout".
-
Implemented the bearer authentication.
-
Added an "Ignore SSL issues" flag.
-
Implemented authentication with a custom header and/or prefix.
EC-Rest 2.0.1
-
Fixed the issue with the post script output returning the following error:
groovy.lang.MissingPropertyException: No such property: sp for class: Rest. -
Documented incompatibilities between v1 and v2.
EC-Rest 2.0.0
-
Major plugin refactoring:
-
New plugin framework used under the cover, making new improvements easier, switched to "ec-groovy".
-
External credentials support has been added.
-
EC-Rest 1.1.1
-
Fixed an issue with ignored proxy configuration for HTTPS.
-
Renamed to CloudBees CD/RO.
EC-Rest 1.1.0
-
Fixed parsing for headers with a whitespace.
-
Support for HTTP Proxy has been provided. Customers who use HTTP proxy can specify Proxy Information (Host, Port and Credentials at the configuration level) and all procedures will use the Proxy as second credentials for authentication.
-
RunRest procedure enhancements:
-
Additional Post Script parameters.
-
Output parameters.
-
Possibility to ignore authentication for a specific request.
-
Possibility to set the cookie value.
-