REST plugin

7 minute readExtensibilityDeveloper productivity

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.0.2022051886

Revised on May 18, 2022

Plugin configurations

Plugin configurations are sets of parameters that apply across some or all of the plugin procedures. They reduce repetition of common values, create predefined parameter sets for end users, and securely store credentials where needed. Each configuration is given a unique name that is entered in designated parameters on procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD, do these steps:

  • Go to Administration Plugins to open the Plugin Manager.

  • Find the EC-Rest-2.3.0.2022051886 row.

  • Click Configure to open the Configurations page.

  • Click Create Configuration as per the description of parameters below.

Configuration procedure parameters

ParameterDescription

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: a 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.:

* GitHub PAT: Authorization: Token ghp_XXXXXXXXXXXXXXXXXXXXXXXXX

* Octopus Deploy: X-Octopus-ApiKey: API-XXXXXXXXXXXXXXXXXXXXXXXXX

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 debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

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

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

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. eg.: 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})?

Output parameters

ParameterDescription

headers

Headers type from response

cookie

Cookie from response

body

The response body or path to target file.

runRest Form

procedure-form

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.

Results and outputs

When the job finished, you can see the response of the server:

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:

Results and outputs

Once the job finished, you can see the response of the server:

Release notes

EC-Rest 2.3.0

  • Added response polling to runRest procedure.

  • Upgraded Spring-Web to v5.3.20

EC-Rest 2.2.6

  • Updated dependencies

  • [Added handling response case:204 No Content]

EC-Rest 2.2.5

  • Upgraded Jackson-Databind to v2.13.2.2

EC-Rest 2.2.4

  • Upgraded dependencies

EC-Rest 2.2.3

  • Upgraded dependencies

  • Added support content type application/vnd.kafka.json.v2+json

EC-Rest 2.2.2

  • Upgraded Jackson-Databind to v2.13.1

EC-Rest 2.2.1

  • Upgraded dependencies

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.1.1

  • Fixed "does not have modify privilege" error when running on non-local resource.

EC-Rest 2.1.0

  • Added support for Plugin Configuration API.

EC-Rest 2.0.2

  • Upgraded third-party libraries.

EC-Rest 2.0.1

  • Fixed the issue with post script output throwing 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 was been added

EC-Rest 1.1.2

  • The documentation has been migrated to the main documentation site.

EC-Rest 1.1.1

  • Fixed an issue with ignored proxy configuration for HTTPS.

  • Renamed to CloudBees CD.

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.

EC-Rest 1.0.9

  • Added metadata that is required for 9.0 release.

EC-Rest 1.0.8

  • Fixed issue with configurations being cached for IE.

EC-Rest 1.0.7

  • Add support for Commander credentials for basic authentication.

  • Mask credentials in step log file.

EC-Rest 1.0.6

  • Add support for the HTTP PATCH, HEAD, and OPTIONS methods.

EC-Rest 1.0.5

  • Add the HTTP PATCH, HEAD, and OPTIONS methods.

EC-Rest 1.0.4

  • Remove the shared plugins directory dependence.

EC-Rest 1.0.3

  • Fix system test issue.

EC-Rest 1.0.2

  • Improve URL validation in the port section.

EC-Rest 1.0.1

  • Add the option to store the response on a property.

EC-Rest 1.0.0

  • Add the runRest procedure.

  • Implement the XML parameter panel

  • Create the help page.

  • Create detailed examples.

  • Add the Postp implementation.