Introduction

A toolchain is a set of tools that supports development, deployment, and operational tasks. A tool is an instance that represents its corresponding tool, such as a GitHub tool, a Slack tool, and so on. For more information about the tools that are supported in Continuous Delivery, see Continuous Delivery integrations. Each toolchain is associated with a resource group, where you can manage user access control by using IBM Cloud Identity and Access Management (IAM).

The Toolchain API provides the following functions, based on the user's IAM permissions:

  • Read a toolchain
  • Create a toolchain
  • Update a toolchain
  • Delete a toolchain and its tools
  • Read a tool
  • Provision a tool
  • Update a tool
  • De-provision a tool

For more information about toolchains, see Creating toolchains.

toolchain-go-sdk is the official Toolchain SDK for the Go programming language.

Run the go get command to retrieve the Toolchain SDK and add it to the GOPATH workspace or to the project's Go module dependencies.

go get github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2

To retrieve the latest version of the SDK, type go get -u:

go get -u github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2

To use the Toolchain SDK within a program, import the package by running the go build or go mod tidy commands to load the package.

import (
	"github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
)

Endpoint URL

The Toolchain API uses the following regional endpoint URLs. When you call the API, add the path for each method to form the complete API endpoint for your requests.

  • Dallas: https://api.us-south.devops.cloud.ibm.com/v2
  • Washington DC: https://api.us-east.devops.cloud.ibm.com/v2
  • London: https://api.eu-gb.devops.cloud.ibm.com/v2
  • Frankfurt: https://api.eu-de.devops.cloud.ibm.com/v2
  • Sydney: https://api.au-syd.devops.cloud.ibm.com/v2
  • Tokyo: https://api.jp-tok.devops.cloud.ibm.com/v2
  • Osaka: https://api.jp-osa.devops.cloud.ibm.com/v2
  • Toronto: https://api.ca-tor.devops.cloud.ibm.com/v2
  • São Paulo: https://api.br-sao.devops.cloud.ibm.com/v2

Example request to the Toolchain API (Dallas)

curl -X <HTTP_METHOD> "https://api.us-south.devops.cloud.ibm.com/v2/<ENDPOINT_PATH>"

Where <HTTP_METHOD> is the appropriate HTTP method, such as GET or POST, and <ENDPOINT_PATH> is an endpoint that is provided by the Toolchain API.

Example of constructing the toolchain service client pointed at a specific region

First construct the toolchain client

import (
	"github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
)
...
toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)

By default, the SDK points at the Dallas URL. A different target region can be set using SetServiceURL

toolchainClient.SetServiceURL(endpointUrl)

Authentication

Authentication to the Toolchain API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. This token is used to determine the actions that a user or service ID can access when they use the API.

For more information about obtaining an IAM token for an authenticated user or service ID, see the IAM Identity Services API documentation.

To use the Toolchain API, add a valid IAM token to the HTTP Authorization request header, for example, -H "Authorization: Bearer <IAM_TOKEN>".

Example request to generate an access token:

curl -X POST
https://iam.cloud.ibm.com/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Where <API_KEY> is your IBM Cloud API Key. Use the resulting IAM token value prefixed by Bearer to authenticate into the Toolchain API.

Example Authorization header value:

Bearer poJraWQiOiIyMDIxMTAzMDE1MTQiLCJhbGciiuJSUzI1NiJ9.eyJpYW1fdWQiOiJJQk1pZC0xMTAwMDBCS1VWIiwiaWQiOiJJQk1pZC0xMTAwMDBCS1VWIiwicmVhbG1pZCI6IklCTWlkIiwianRpIjoiMjgzMDE3MWItYmY1MC00ZGEyLWE4MjAtMjFmNGVjYWQ0NDE0IiwiaWRlbnRkj

To authenticate into the toolchain service through the Go SDK, an IAM API key. To obtain an API key, access the IBM Cloud API keys page and create an API key.

The IAM API key can be passed to the toolchain Go SDK through environment variables

export CD_TOOLCHAIN_AUTHTYPE=iam
export CD_TOOLCHAIN_APIKEY=<IAM_API_KEY>

Error handling

The Toolchain API uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range indicates a failure, and a response in the 5xx range typically indicates an internal system error that cannot be resolved by the user. The following tables show the response codes and methods.

ErrorResponse

Name Description
status_code
integer
The HTTP response code.
trace
string
The unique ID that is used to trace an error.
errors
ErrorDetail[]
The collection of error details that is encountered in the request.

ErrorDetail

Name Description
code
string
An indicator that describes a specific error.
message
string
The short description of a specific error.

Methods

Returns a list of toolchains

Returns a list of toolchains that the caller is authorized to access and that meet the provided query parameters.

GET /toolchains

Request

Query Parameters

  • The resource group ID where the toolchains exist

    Possible values: length = 32, Value must match regular expression ^[0-9a-f]{32}$

  • Limit the number of results. Valid value 0 < limit <= 200.

    Possible values: 1 ≤ value ≤ 200

    Default: 20

  • Offset the number of results from the beginning of the list. Valid value 0 <= offset < 200.

    Possible values: 0 ≤ value ≤ 199

    Default: 0

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --get --data "resource_group_id={resource_group_id}" --data "limit={limit}" --data "offset={offset}"   "{base_url}/toolchains"
  • listToolchainsOptions := toolchainClient.NewListToolchainsOptions(resourceGroupId)
    listToolchainsOptions.SetLimit(limit)
    listToolchainsOptions.SetOffset(offset)
    
    toolchains, response, err := toolchainClient.ListToolchains(listToolchainsOptions)

Response

Response structure for GET toolchains

Status Code

  • Successful request

  • Missing toolchain parameters or unsupported toolchain

  • Returned when the provided resource group ID is not found or accessible.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "limit": 3,
      "offset": 6,
      "total_count": 12,
      "first": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&limit=3"
      },
      "next": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&offset=9&limit=3"
      },
      "previous": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&offset=3&limit=3"
      },
      "last": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains?resource_group_id=6a9a01f2cff54a7f966f803d92877123&offset=9&limit=3"
      },
      "toolchains": [
        {
          "id": "eadef4f3-8e39-4669-86f4-e55051a12338",
          "name": "TestToolchainV2-1",
          "description": "A sample toolchain",
          "account_id": "f2337426699b4041bc50f1d45042f777",
          "location": "us-south",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:eadef4f3-8e39-4669-86f4-e55051a12338::",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/eadef4f3-8e39-4669-86f4-e55051a12338",
          "created_at": "2021-05-05T17:07:09.354Z",
          "updated_at": "2022-01-01T13:13:07.968Z",
          "created_by": "IBMid-123456AB7C",
          "tags": [
            "string"
          ]
        },
        {
          "id": "62935028-0202-48fe-b877-7e99c817b856",
          "name": "TestToolchainV2-2",
          "description": "A second sample toolchain",
          "account_id": "f2337426699b4041bc50f1d45042f777",
          "location": "us-south",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:62935028-0202-48fe-b877-7e99c817b856::",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/62935028-0202-48fe-b877-7e99c817b856",
          "created_at": "2021-05-05T17:07:09.354Z",
          "updated_at": "2022-01-01T13:13:07.968Z",
          "created_by": "IBMid-123456AB7C",
          "tags": [
            "string"
          ]
        },
        {
          "id": "a8334cb6-87a2-4308-8bf0-681f7b418f37",
          "name": "TestToolchainV2-3",
          "description": "A third sample toolchain",
          "account_id": "f2337426699b4041bc50f1d45042f777",
          "location": "us-south",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:a8334cb6-87a2-4308-8bf0-681f7b418f37::",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/a8334cb6-87a2-4308-8bf0-681f7b418f37",
          "created_at": "2021-05-05T17:07:09.354Z",
          "updated_at": "2022-01-01T13:13:07.968Z",
          "created_by": "IBMid-123456AB7C",
          "tags": [
            "string"
          ]
        }
      ]
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Create a toolchain

Creates a new toolchain based off of provided parameters in the POST body.

POST /toolchains

Request

Body structure for creating a toolchain.

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "{toolchain_name}", "resource_group_id": "{resource_group_id}", "description": "{toolchain_description}" }'   "{base_url}/toolchains"
  • createToolchainOptions := toolchainClient.NewCreateToolchainOptions(toolchainName, resourceGroupId)
    createToolchainOptions.SetDescription(toolchainDescription)
    
    toolchain, response, err := toolchainClient.CreateToolchain(createToolchainOptions)

Response

POST toolchain response body

Status Code

  • Toolchain successfully created, URL of new toolchain returned in Location header

  • Returned when there are missing toolchain properties or when attempting to create more than the maximum number of toolchains allowed per resource group.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
      "location": "us-south",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "TestToolchainV2",
      "description": "A sample toolchain to test the API",
      "created_at": "2021-05-05T17:07:09.354Z",
      "created_by": "IBMid-123456AB7C",
      "updated_at": "2021-05-05T17:07:09.354Z",
      "tags": []
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Fetch a toolchain

Returns data for a single toolchain identified by id.

GET /toolchains/{toolchain_id}

Request

Path Parameters

  • ID of the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   "{base_url}/toolchains/{toolchain_id}"
  • getToolchainByIDOptions := toolchainClient.NewGetToolchainByIDOptions(toolchainId)
    
    toolchain, response, err := toolchainClient.GetToolchainByID(getToolchainByIDOptions)

Response

Response structure for GET toolchains

Status Code

  • Successful request

  • Missing toolchain parameters or unsupported toolchain

  • Returned when the provided toolchain ID is not found or accessible.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
      "location": "us-south",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "TestToolchainV2",
      "description": "A sample toolchain to test the API",
      "created_at": "2021-05-05T17:07:09.354Z",
      "created_by": "IBMid-123456AB7C",
      "updated_at": "2021-05-05T17:07:09.354Z",
      "tags": []
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Delete a toolchain

Delete the toolchain with the specified ID.

DELETE /toolchains/{toolchain_id}

Request

Path Parameters

  • ID of the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   "{base_url}/toolchains/{toolchain_id}"
  • deleteToolchainOptions := toolchainClient.NewDeleteToolchainOptions(toolchainId)
    
    response, err := toolchainClient.DeleteToolchain(deleteToolchainOptions)

Response

Status Code

  • Toolchain successfully deleted.

  • Missing path parameters.

  • Returned when the provided toolchain ID is not found or accessible, or unsupported toolchain.

  • Returned when the Customer Root Ket is not active for the provided toolchain(s).

  • Returned when a system/database error is encountered.

Example responses
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 412,
      "errors": [
        {
          "code": "precondition_failed",
          "message": "The target resource is not in the appropriate state for that action."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Update a toolchain

Update the toolchain with the specified ID.

PATCH /toolchains/{toolchain_id}

Request

Path Parameters

  • ID of the toolchain

Body structure for the update toolchain PATCH request.

  • curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/merge-patch+json"   --data '{ "name": "{new_toolchain_name}", "description": "{new_toolchain_description}" }'   "{base_url}/toolchains/{toolchain_id}"
  • updateToolchainOptions := toolchainClient.NewUpdateToolchainOptions(toolchainId)
    updateToolchainOptions.SetName(newToolchainName)
    updateToolchainOptions.SetDescription(newToolchainDescription)
    
    toolchain, response, err := toolchainClient.UpdateToolchain(updateToolchainOptions)

Response

PATCH toolchain response body

Status Code

  • Toolchain successfully updated

  • Missing toolchain parameters or unsupported toolchain.

  • Returned when the provided toolchain ID is not found or accessible.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:ec58a911-c217-4e56-a40b-93482cd18706::",
      "location": "us-south",
      "account_id": "f2337426699b4041bc50f1d45042f777",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "newToolchainName",
      "description": "New toolchain description",
      "created_at": "2021-05-05T17:07:09.354Z",
      "created_by": "IBMid-123456AB7C",
      "updated_at": "2022-01-01T13:13:07.968Z",
      "tags": []
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Returns a list of tools bound to toolchain

Returns a list of tools bound to toolchain that the caller is authorized to access and that meet the provided query parameters.

GET /toolchains/{toolchain_id}/tools

Request

Path Parameters

  • ID of the toolchain that tools are bound to

Query Parameters

  • Limit the number of results. Valid value 0 < limit <= 200.

    Possible values: 1 ≤ value ≤ 200

    Default: 20

  • Offset the number of results from the beginning of the list. Valid value 0 <= offset < 200.

    Possible values: 0 ≤ value ≤ 199

    Default: 0

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --get --data "limit={limit}" --data "offset={offset}"   "{base_url}/toolchains/{toolchain_id}/tools"
  • listToolsOptions := toolchainClient.NewListToolsOptions(toolchainId)
    listToolsOptions.SetLimit(limit)
    listToolsOptions.SetOffset(offset)
    
    tools, response, err := toolchainClient.ListTools(listToolsOptions)

Response

Response structure for GET tools

Status Code

  • Successful request

  • Missing toolchain parameters or unsupported toolchain

  • Returned when the provided resource group ID is not found or accessible.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "limit": 3,
      "offset": 6,
      "total_count": 12,
      "first": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?limit=3"
      },
      "previous": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?offset=3&limit=3"
      },
      "next": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?offset=9&limit=3"
      },
      "last": {
        "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools?offset=9&limit=3"
      },
      "tools": [
        {
          "id": "2983b160-fc37-4c45-8a8f-e616ad7e470b",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:2983b160-fc37-4c45-8a8f-e616ad7e470b",
          "name": "MyTool-1",
          "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
          "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
          "tool_type_id": "todolist",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/2983b160-fc37-4c45-8a8f-e616ad7e470b",
          "referent": {
            "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/90656940e53cd382ee57827df6e2axd3c"
          },
          "updated_at": "2022-01-01T13:13:07.968Z",
          "parameters": {
            "label": "list-1"
          },
          "state": "configured"
        },
        {
          "id": "9dd0c477-f173-4c3f-a7cf-d27026ace379",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:9dd0c477-f173-4c3f-a7cf-d27026ace379",
          "name": "MyTool-2",
          "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
          "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
          "tool_type_id": "todolist",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/9dd0c477-f173-4c3f-a7cf-d27026ace379",
          "referent": {
            "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/gveqmwe9ijxqru767r6yingjxrq46pjvt"
          },
          "updated_at": "2022-01-01T13:13:07.968Z",
          "parameters": {
            "label": "list-2"
          },
          "state": "configured"
        },
        {
          "id": "93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
          "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
          "name": "MyTool-3",
          "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
          "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
          "tool_type_id": "todolist",
          "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
          "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/93f7a2b1-a1cb-46f2-9ab7-dc2e3443dd3e",
          "referent": {
            "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/vqr3abthqewz9fkznx3yg9uwdxhy338m2"
          },
          "updated_at": "2022-01-01T13:13:07.968Z",
          "parameters": {
            "label": "list-3"
          },
          "state": "configured"
        }
      ]
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Create a tool

Provisions a new tool based off of provided parameters in the POST body and binds it to the specified toolchain.

POST /toolchains/{toolchain_id}/tools

Request

Path Parameters

  • ID of the toolchain to bind tool to

Details on the new tool

  • curl -X POST --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   --data '{ "name": "{tool_name}", "tool_type_id": "{tool_type_id}", "parameters": {json_parameters_object} }'   "{base_url}/toolchains/{toolchain_id}/tools"
  • createToolOptions := toolchainClient.NewCreateToolOptions(toolchainId, toolTypeId)
    createToolOptions.SetName(toolName)
    createToolOptions.SetParameters(toolParameters)
    
    tool, response, err := toolchainClient.CreateTool(createToolOptions)

Response

POST tool response body

Status Code

  • Toolchain successfully created, URL of new toolchain returned in Location header

  • Returned when there are missing toolchain properties or when attempting to create more than the maximum number of toolchains allowed per resource group.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "MyTool",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "todolist",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
      "referent": {
        "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/90656940e53cd382ee57827df6e2axd3c"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "test-v2-label"
      },
      "state": "configured"
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Fetch a tool

Returns a tool that is bound to the provided toolchain.

GET /toolchains/{toolchain_id}/tools/{tool_id}

Request

Path Parameters

  • ID of the toolchain

  • ID of the tool bound to the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • getToolByIDOptions := toolchainClient.NewGetToolByIDOptions(toolchainId, toolId)
    
    tool, response, err := toolchainClient.GetToolByID(getToolByIDOptions)

Response

Response structure for GET tool

Status Code

  • Successful request

  • Missing or invalid toolchain and tool parameters

  • Returned when the provided tool ID is not found or accessible.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "MyTool",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "todolist",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
      "referent": {
        "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/90656940e53cd382ee57827df6e2axd3c"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "test-v2-label"
      },
      "state": "configured"
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Delete a tool

Delete the tool with the specified ID.

DELETE /toolchains/{toolchain_id}/tools/{tool_id}

Request

Path Parameters

  • ID of the toolchain

  • ID of the tool bound to the toolchain

  • curl -X GET --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • deleteToolOptions := toolchainClient.NewDeleteToolOptions(toolchainId, toolId)
    
    response, err := toolchainClient.DeleteTool(deleteToolOptions)

Response

Status Code

  • Tool successfully deleted.

  • Missing path parameters.

  • Returned when the provided tool ID is not found or accessible, or unsupported toolchain.

  • Returned when the Customer Root Ket is not active for the provided toolchain(s).

  • Returned when a system/database error is encountered.

Example responses
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 404,
      "errors": [
        {
          "code": "not_found_or_accessible",
          "message": "The requested resource was not found or is not accessible."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 412,
      "errors": [
        {
          "code": "precondition_failed",
          "message": "The target resource is not in the appropriate state for that action."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }

Update a tool

Update the tool with the specified ID.

PATCH /toolchains/{toolchain_id}/tools/{tool_id}

Request

Path Parameters

  • ID of the toolchain

  • ID of the tool bound to the toolchain

Details on the new tool

  • curl -X PATCH --location --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/merge-patch+json"   --data '{ "name": "{new_tool_name}", "parameters": {new_json_parameters_object} }'   "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
  • updateToolOptions := toolchainClient.NewUpdateToolOptions(toolchainId, toolId)
    updateToolOptions.SetName(newToolName)
    updateToolOptions.SetParameters(newToolParameters)
    
    tool, response, err := toolchainClient.UpdateTool(updateToolOptions)

Response

PATCH tool response body

Status Code

  • Tool successfully updated.

  • Returned when there are missing required tool properties or bad format.

  • Returned when there are conflicting service IDs in the request body and the tool.

  • Returned when a system/database error is encountered.

Example responses
  • {
      "id": "ec58a911-c217-4e56-a40b-93482cd18706",
      "crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e:tool:ec58a911-c217-4e56-a40b-93482cd18706",
      "name": "MyTool",
      "toolchain_id": "d02d29f1-e7bb-4977-8a6f-26d7b7bb893e",
      "toolchain_crn": "crn:v1:staging:public:toolchain:us-south:a/f2337426699b4041bc50f1d45042f777:d02d29f1-e7bb-4977-8a6f-26d7b7bb893e::",
      "tool_type_id": "todolist",
      "resource_group_id": "6a9a01f2cff54a7f966f803d92877123",
      "href": "https://api.us-south.devops.dev.cloud.ibm.com/v2/toolchains/d02d29f1-e7bb-4977-8a6f-26d7b7bb893e/tools/ec58a911-c217-4e56-a40b-93482cd18706",
      "referent": {
        "ui_href": "https://otc-todolist-service.us-south.devops.dev.cloud.ibm.com/todo/90656940e53cd382ee57827df6e2axd3c"
      },
      "updated_at": "2022-01-01T13:13:07.968Z",
      "parameters": {
        "label": "test-v2-label"
      },
      "state": "configured"
    }
  • {
      "status_code": 400,
      "errors": [
        {
          "code": "invalid_request",
          "message": "The request contained an invalid body or one or more invalid parameters"
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 409,
      "errors": [
        {
          "code": "conflict",
          "message": "The target resource is already in the requested state."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }
  • {
      "status_code": 500,
      "errors": [
        {
          "code": "unknown",
          "message": "Oops! Something went wrong. The system might be experiencing problems. Try again in a few minutes."
        }
      ],
      "trace": "3KADyw3zCjKvP5LkC1L3wM"
    }