Problem
Using the CloudBees CD REST API explains the CD REST API in details. However, you may need to access the CD REST API in some cases that the documentation does not cover. For example, you may need to access it with a command line to test it, you may want to call it from a Pipeline, or get some data from the CD server from a machine where ectool/ec-perl is not available.
Solution
You can use the curl to access the CloudBees CD (CloudBees Flow) server REST API. Here are some tips:
Figuring out the API call to make
One way to figure out what REST API call you would like to use is to Access the Swagger UI.
This will give you an easy way to choose the options for the API call, and it will generate the exact curl command you can run inside your pipeline:
How to call the API in a Pipeline, and set a property with the result
To call the API from a Pipeline, you would use a command step:
The first step of my Pipeline stage gets the credential, calls the API, echos the result, then sets a property with the result:
ectool attachCredential testA /projects/testA/credentials/myCredential --pipelineName "callAPI" --stageName "callAPI" --taskName "callAPI" USER=$(ectool getFullCredential /projects/testA/credentials/myCredential --value userName) PASS=$(ectool getFullCredential /projects/testA/credentials/myCredential --value password) RESULT=$(curl -k -u $USER:$PASS -X GET "https://localhost/rest/v1.0/availableResources?request=resourceForEnvironment&includePoolUsage=true" -H "accept: application/json") echo "$RESULT" ectool setProperty /myPipelineRuntime/stages/callAPI/result "$RESULT"
The code from the second step fetches that property and echos it is:
MY_RESULT=$(ectool getProperty /myPipelineRuntime/stages/callAPI/result) echo "MY_RESULT=$MY_RESULT"
An animated GIF of running the Pipeline and seeing the result in CloudBees CD v10.0 is:
Encountering a "SSL certificate problem: self signed certificate" error
You may get the error "curl: (60) SSL certificate problem: self signed certificate" like what happens in the following case:
$ curl -X GET --header "Accept: application/json" "https://flowserver/rest/v1.0/server/info" curl: (60) SSL certificate problem: self signed certificate More details here: https://curl.se/docs/sslcerts.html curl failed to verify the legitimacy of the server and therefore could not establish a secure connection to it. To learn more about this situation and how to fix it, please visit the web page mentioned above.
You can use the "-k" option to disable certificate checks, like the following example:
$ curl -k -X GET --header "Accept: application/json" "https://flowserver/rest/v1.0/server/info"
{"serverInfo":{"cluster":"0","httpPort":"8000","httpsPort":"8443","jobEventsDestination":"/topic/events.job","jobEventsSelector":"path = '/jobs/$[jobId]'","putFileDestination":"/queue/jobs.$[jobId]","putFileSelector":"command='PUT_FILE' AND channel='$[channel]'","stompClientUri":"stomp+ssl://flowserver:61613"}}
Or you can add the certificate of the CD server into the certificate store on the machine you are running curl from, using the solution from this article.
Using the "-u" option to set credentials to access the CloudBees CD (CloudBees Flow) server
Please note that the API "getServerInfo" in the previous example is an API that does not require the caller has access rights to the CloudBees CD (CloudBees Flow) server. Most of the CloudBees CD (CloudBees Flow) REST APIs do require the caller has access right to the CloudBees CD (CloudBees Flow) server. For example:
$ curl -k -X GET --header "Accept: application/json" "https://flowserver/rest/v1.0/licenses"
{"error":{"where":"","message":"No credentials/session found in this request","details":"","code":"NoCredentials"}}
You can use the "-u" option to provide the credentials like the following example:
$ curl -k -u admin:<PASSWORD> -X GET --header "Accept: application/json" "https://flowserver/rest/v1.0/licenses"
{"license":[{"licenseId":"cd00da46-e03e-11e9-9e41-de4420524153","productName":"ElectricCommander","createTime":"2019-09-26T09:19:53.786Z","customerName":"Electric Cloud, Inc.","evaluation":"0","featureName":"Server","gracePeriod":"0","lastModifiedBy":"admin","modifyTime":"2019-09-26T09:19:53.786Z","owner":"admin","signature":"<HIDDEN>","propertySheet":{"propertySheetId":"cd00da47-e03e-11e9-9e41-de4420524153","createTime":"2019-09-26T09:19:53.786Z","credentialProtected":"0","lastModifiedBy":"admin","modifyTime":"2019-09-26T09:19:53.786Z","owner":"admin","tracked":"0","property":[{"propertyId":"cd2244f8-e03e-11e9-9e41-de4420524153","propertyName":"editionName","createTime":"2019-09-26T09:19:53.786Z","expandable":"1","lastModifiedBy":"admin","modifyTime":"2019-09-26T09:19:53.786Z","owner":"admin","suppressValueTracking":"0","tracked":"0","value":"standard"},{"propertyId":"cd2bbad9-e03e-11e9-9e41-de4420524153","propertyName":"maxConcurrentSteps","createTime":"2019-09-26T09:19:53.786Z","expandable":"1","lastModifiedBy":"admin","modifyTime":"2019-09-26T09:19:53.786Z","owner":"admin","suppressValueTracking":"0","tracked":"0","value":"2"}]}}]}
Please note that the password in the command and the signature in the output are replaced by "<PASSWORD>" and "<HIDDEN>".
For an example on retrieving the username and password from a credential in CD, follow the steps in section How to call the API in a Pipeline, and set a property with the result above.