Introduction

IBM® Blockchain Platform provides a managed and full stack blockchain-as-a-service (BaaS) offering. It simplifies your journey to build a Hyperledger Fabric based blockchain network and allows you to deploy blockchain components in environments of your choice.

These APIs are for provisioning Fabric components and administering the IBM Blockchain Platform console. They do not include Fabric operations.

- Use Fabric CA APIs to perform CA operations such as registering or enrolling users.
- Use Fabric SDKs or Peer CLI commands to perform other Fabric operations.

Updates

August 2020

  • Updated configuration override options
    • More config settings are editable via config_override.
  • Go SDK Docs/Examples
    • A GoLang SDK/module for IBP APIs is available. Details.

March 2020

  • v2 APIs
    • New IBM Blockchain Platform console APIs using the route /v2/ are now available. Use of the earlier /v1/ APIs continues to be supported.
  • Configuration override
    • The IBM® Blockchain Platform APIs have been updated to allow you to customize the deployment of your component. The Fabric Certificate authority (CA), peer, and ordering node configuration files can now be customized by sending a configuration override in JSON. For more information, see Configuration Override.

Authentication (IBM Cloud only)

  • If you are looking for instructions on using APIs with the IBM Blockchain Platform on the OpenShift Container Platform or Kubernetes refer to these instructions for authentication instead.

  • If you are looking for instructions on using APIs with the IBM Blockchain on IBM Cloud, they are below:

Introduction

To authenticate an API request, you need to provide an access/bearer token in the request. To do that we first need to create a service credential, then exchange the API key from the service credential for an access/bearer token. Finally, construct the authorization header with the access/bearer token.

To start, gather the following:

  • API-Key and API-Endpoint

    The (IAM) API key is used to authenticate your requests to your IBM Blockchain Platform service instance. The API-Endpoint is the url that allows you to access your service instance.

    You can get the API key and API Endpoint by creating a new service credential for your service instance:

    1. In your IBM Cloud dashboard, open the IBM Blockchain Platform service instance that you created.
    2. Click Service credentials from the left navigator.
    3. Click the "New Credential" button on the Service credentials page to create a new credential.
      1. Give the credential a Name to remember its purpose. Example, Test Service Credential.
      2. Select a permission (Manager, Writer, or Reader) from the Role drop-down. For more information about each role, see the table in Add and remove users from the console.
      3. Ignore the optional Select Service ID drop-down.
      4. Ignore the optional Inline configuration Parameters text-area.
      5. Click the Add button.
    4. After the new credential is created, click View credentials under the Actions table header. The field api_endpoint value is your API-Endpoint and the apikey value is your API-Key. An example service credential is shown in right pane ->.
      • apikey - This field is your IAM API key. The example steps on this page refer to this field as {API-Key}. It is a secret/password that does not expire. Keep this key in a secure location. You will use this value in the next step.
      • api_endpoint - This is your IBM Blockchain Platform console url. All API requests need be sent to this url. The examples in the right pane will use the symbol {API-Endpoint} to refer to this field. When copying an example, replace this text (including the brackets) with the url of your IBP console. Your url will look similar to https://abcd-ibpconsole-console.uss01.blockchain.cloud.ibm.com.
  • Access-Token

    Authenticate your app or service by including your IBM Cloud IAM access token (also known as a bearer token) in the API requests. We will build the authorization header next, first lets get the access token:

    1. To generate an access token, you must send the IAM API-Key to an IAM exchange endpoint. The response will have an access/bearer token that is good for 1 hour. There is a curl example in the right pane -> and details below:

      • Method: POST
      • Endpoint: "https://iam.cloud.ibm.com/identity/token"
      • Data: "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={API-Key}"
        • Replace {API-Key} including the brackets with your key.

      Access/bearer tokens are valid for one hour, but you can regenerate them as needed. To maintain access to the service, refresh the access token regularly.

Build Header

Using the response of the access token api call you can now create the http Authorization header. This header authorizes all IBP console APIs (given the IAM API key has the necessary role). It should follow this format:

Authorization: Bearer {Access-Token}
  • If you are using curl, the header can be set with this argument: -H "Authorization: Bearer {Access-Token}"
  • Replace the text {Access-Token} (including the brackets) with the value of your access_token field. However, note that the JSON response contains multiple fields. Only copy the value of the access_token field.
  • With the Authorization header set, the hard part is done. Next pick an api, set the route, set a body (if applicable) and fire!

API-Key and API-Endpoint.

The service credential looks similar to the following example, where the api_endpoint value is your API Endpoint and the apikey value is your API key.

// example service credential:

{
  "api_endpoint": "https://abcd-ibpconsole-console.uss01.blockchain.cloud.ibm.com",

  "apikey": "1234s4eoUn7aBRRngGkgYKPqtP3h81ByLs7xHcqJ_aReu",

  "iam_apikey_description": "Auto-generated for key abcd-1234-5678-ba06-23c43053df8c",

  "iam_apikey_name": "my test key",

  "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",

  "iam_serviceid_crn": "crn:v1:staging:public:iam-identity::a/1234037caee397faa45c55e087d26baa::serviceid:ServiceId-12345-9c37-4f68-8572-8d6e2aabbc7e"
}

Access-Token

Open a terminal and call this IAM API to generate an access/bearer token. First, replace the {API-Key} with the apikey value in your service credential.

curl -X POST "https://iam.cloud.ibm.com/identity/token"   -H "Accept: application/json"   -H "Content-Type: application/x-www-form-urlencoded"   -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={API-Key}"

The response that is returned by this curl command contains multiple fields. Be sure to copy and use the value of the access_token field for the Bearer token authorization header.

// example response (values are abbreviated for brevity):
{
  "access_token": "eyJraWQiOiIyMDE5MDcyNCIsImFsZyI6IlJTMjU2In0.eyJpYW1faWQiTQzM...",

  "refresh_token": "OKCdugM9yM4QAuDqQBXC-FnkcqXGqbQPI5y3dWMDCNbUzXYIO-gwA0LzlFe...",

  "token_type": "Bearer",

  "expires_in": 3600,

  "expiration": 1577854800,

    "scope": "ibm openid"
}

Response Codes

The IBM Blockchain Platform APIs use standard HTTP status codes to indicate whether a method completed successfully. A 200-299 status code indicates a success. A 400-599 status code indicates a failure. All APIs will respond with JSON and set the response header Content-Type to application/json.

HTTP Status Code Description Recovery
2xx OK The request was successful. The response contains details.
4xx Invalid Request There is some issue with the request such as invalid permission, invalid input, or invalid route. Correct and try again.
5xx Internal Error The request could not be processed due to an internal issue or an issue with a dependency. Wait a few minutes and try again.

Rate Limits

All endpoints are protected by a rate limiter. If a client exceeds the limit, the server will not process the request and respond with a status code of 429. The client should back off and try the same request later.

There is a "base" limit of 25 requests per minute which applies to APIs that change state. Requests that do not alter state, such as one's with a GET method, have a a limit of 4 x base or 100 requests per min. These limits can be customized with the Change IBP console settings API.

  • The remaining requests a client can make (of the same type) before hitting the limit can be seen in the response header X-RateLimit-Remaining
  • When the limit is exceeded a UNIX timestamp (UTC) of when the client can retry is returned in the response header X-RateLimit-Reset
  • API rates are applied to individual clients

Examples

This page is broken up into three panes. The leftmost pane contains navigation. The middle pane has API documentation. The far right contains syntax examples of each API.

Curl

A curl example appears to the right of each documented api (if the Curl tab is selected). If you are unfamiliar with cURL, it is free software that allows you to send HTTP requests by using a command line interface. It is the quickest way to interact with the IBM Blockchain Platform APIs.

After curl is installed locally (it is often already installed by many operating systems), you can copy the example curl text and paste it into command line. Remember to replace the placeholders in the curl example with specific values for your service instance.

Most of the curl examples have placeholder values. They need to be replaced to use the API. For example, the fields api_url, grpcwp_url, tls_cert, admins, root_certs & tls_root_certs in all curl examples are examples. They must be replaced with values for your components or identities.

In most cases the API will be rejected if the examples are left unchanged. This is especially true for certificate examples.

Go

A GoLang example appears to the right of each documented api (if the Go tab is selected). The Go examples demonstrate usage with the Go SDK/module. More SDK details.

Postman

APIs are available to download a working Postman collection, which includes example API requests for all the APIs. If you are unfamiliar with Postman, it is free software that allows you to send and save HTTP requests by using a graphical user interface. It is easier to use than curl (less error prone).

See the Generate Postman collection APIs in the Download examples section to download a collection for your preferred auth. When Postman is installed, you can import this collection and then use Postman to interact with the APIs.

Just like the other examples, these examples will contain placeholder values. The placeholder values must be replaced to have a properly working request.

OpenAPI

There is an API to download the OpenAPI file (also known as the swagger file) that is used to build this page. If you are unfamiliar with OpenAPI, it is a file-based documentation standard that allows an application to document supported HTTP requests. Our version of the file documents the APIs offered by the IBM Blockchain Platform console. It is the same file that helped generate the API section below.

After you download the file, you can use it with various tools that support OpenAPI v3. For example, you can copy and paste the file into a swagger editor to browse the APIs we offer through an offline interface. See the Download OpenAPI file API in the Download examples section to get the swagger file.

SDK

A GoLang SDK/module is available. This module will allow you to use native Go functions to leverage the same functionality seen in the IBP APIs on this page. You can also click on the Go tab (near the top of the right pane of this window) to see Go example syntax instead of curl examples (scroll down to an API first).

For SDK installation and auth setup refer to the ibp-go-sdk readme:

The Go examples (in the right pane of this window) contain placeholder text which will need to be replaced. The placeholders will use curly brackets around title case names, such as:

- {API-Endpoint} - Replace this text (including the brackets) with the url of your IBP console. It will be similar to https://abcd-ibpconsole-console.uss01.blockchain.cloud.ibm.com.
- {Component-ID} - Replace this text (including the brackets) with the id of a component. Components ids are strings, similar to mypeer.
- {API-Key} - Replace this text (including the brackets) with your IAM API Key. See that the auth instructions to obtain one.

Configuration override

You have the option of customizing the configuration of a CA, peer, or ordering node by setting the configuration override field in certain APIs. Normally the components that are deployed by the IBM Blockchain console APIs are configured with default Fabric values that are provided by the fabric-ca-server-config.yaml, orderer.yaml, and core.yaml files. However, you can customize your component's settings by providing the field config_override in the body of a create or update component API. The value of the field would contain the desired configuration. You can use the override to deploy a High Availability (HA) CA or deploy components that use a Hardware Security Module (HSM). For more information about the override, High Availability CAs, or HSMs, see Advanced deployment options.

You can find the configuration fields documented in the Fabric configuration sample files:

Examples

Methods

Get component data

Get the IBP console's data on a component (peer, CA, orderer, or MSP). The component might be imported or created.

Get the IBP console's data on a component (peer, CA, orderer, or MSP). The component might be imported or created.

GET /ak/api/v2/components/{id}
(blockchain *BlockchainV2) GetComponent(getComponentOptions *GetComponentOptions) (result *GenericComponentResponse, response *core.DetailedResponse, err error)

Request

Instantiate the GetComponentOptions struct and set the fields to provide parameter values for the GetComponent method.

Path Parameters

  • The id of the component to retrieve. Use the Get all components API to determine the component id.

Query Parameters

  • Set to 'included' if the response should include Kubernetes deployment attributes such as 'resources', 'storage', 'zone', 'region', 'admin_certs', etc. Default responses will not include these fields.

    This parameter will not work on imported components.

    It's recommended to use cache=skip as well if up-to-date deployment data is needed.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'included' if the response should include parsed PEM data along with base 64 encoded PEM string. Parsed certificate data will include fields such as the serial number, issuer, expiration, subject, subject alt names, etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • Set to 'included' if the response should fetch CA attributes, inspect certificates, and append extra fields to CA and MSP component responses.

    • CA components will have fields appended/updated with data fetched from the /cainfo?ca=ca endpoint of a CA, such as: ca_name, root_cert, fabric_version, issuer_public_key and issued_known_msps. The field issued_known_msps indicates imported IBP MSPs that this CA has issued. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported MSPs are checked. Default responses will not include these fields.
    • MSP components will have the field issued_by_ca_id appended. This field indicates the id of an IBP console CA that issued this MSP. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported/created CAs are checked. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

The GetComponent options.

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}?cache=skip&deployment_attrs=included" -H "Authorization: Bearer {Access-Token}"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
        ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
        URL: "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := NewBlockchainV2(options)
    if err != nil {
        return
    }
    
    // Get data for component "{Component-ID}"
    opts := service.NewGetComponentOptions("{Component-ID}")
    result, detailedResponse, err := service.GetComponent(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a component. Not all components have the same fields, see description of each field for details.

Contains the details of a component. Not all components have the same fields, see description of each field for details.

Status Code

  • Request was successful.

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Remove imported component

Remove a single component from the IBP console.

  • Using this api on an imported component removes it from the IBP console.
  • Using this api on a created component removes it from the IBP console but it will not delete the component from the Kubernetes cluster where it resides. Thus it orphans the Kubernetes deployment (if it exists). Instead use the Delete component API to delete the Kubernetes deployment and the IBP console data at once.

Remove a single component from the IBP console.

  • Using this api on an imported component removes it from the IBP console.
  • Using this api on a created component removes it from the IBP console but it will not delete the component from the Kubernetes cluster where it resides. Thus it orphans the Kubernetes deployment (if it exists). Instead use the Delete component API to delete the Kubernetes deployment and the IBP console data at once.
DELETE /ak/api/v2/components/{id}
(blockchain *BlockchainV2) RemoveComponent(removeComponentOptions *RemoveComponentOptions) (result *DeleteComponentResponse, response *core.DetailedResponse, err error)

Request

Instantiate the RemoveComponentOptions struct and set the fields to provide parameter values for the RemoveComponent method.

Path Parameters

  • The id of the imported component to remove. Use the Get all components API to determine the component id.

The RemoveComponent options.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}" -H "Authorization: Bearer {Access-Token}"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
        ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
        URL: "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := NewBlockchainV2(options)
    if err != nil {
        return
    }
    
    // Remove component
    opts := service.NewRemoveComponentOptions("myca")
    result, detailedResponse, err := service.RemoveComponent(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Status Code

  • Request was successful.

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

Example responses

Delete component

Removes a single component from the IBP console and it deletes the Kubernetes deployment.

  • Using this api on an imported component will error out since its Kubernetes deployment is unknown and cannot be removed. Instead use the Remove imported component API to remove imported components.
  • Using this api on a created component removes it from the IBP console and it will delete the component from the Kubernetes cluster where it resides. The Kubernetes delete must succeed before the component will be removed from the IBP console.

Removes a single component from the IBP console and it deletes the Kubernetes deployment.

  • Using this api on an imported component will error out since its Kubernetes deployment is unknown and cannot be removed. Instead use the Remove imported component API to remove imported components.
  • Using this api on a created component removes it from the IBP console and it will delete the component from the Kubernetes cluster where it resides. The Kubernetes delete must succeed before the component will be removed from the IBP console.
DELETE /ak/api/v2/kubernetes/components/{id}
(blockchain *BlockchainV2) DeleteComponent(deleteComponentOptions *DeleteComponentOptions) (result *DeleteComponentResponse, response *core.DetailedResponse, err error)

Request

Instantiate the DeleteComponentOptions struct and set the fields to provide parameter values for the DeleteComponent method.

Path Parameters

  • The id of the component to delete. Use the Get all components API to determine the id of the component to be deleted.

The DeleteComponent options.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/kubernetes/components/{Component-ID}" -H "Authorization: Bearer {Access-Token}"
  • // Create an authenticator
     authenticator := &core.IamAuthenticator{
         ApiKey: "{API-Key}",
     }
    
     // Create an instance of the "BlockchainV2Options" struct
     options := &blockchainv2.BlockchainV2Options{
         Authenticator: authenticator,
         URL: "https://{API-Endpoint}",
     }
    
     // Create an instance of the "BlockchainV2" service client.
     service, err := NewBlockchainV2(options)
     if err != nil {
         return
     }
    
     // Delete component
     opts := service.NewDeleteComponentOptions("myca")
     replace, detailedResponse, err := service.DeleteComponent(opts)
     fmt.Println("result:", replace)
     fmt.Println("response:", detailedResponse)

Response

Status Code

  • Request was successful.

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Create a CA

Create a Hyperledger Fabric Certificate Authority (CA) in your Kubernetes cluster.

Create a Hyperledger Fabric Certificate Authority (CA) in your Kubernetes cluster.

POST /ak/api/v2/kubernetes/components/fabric-ca
(blockchain *BlockchainV2) CreateCa(createCaOptions *CreateCaOptions) (result *CaResponse, response *core.DetailedResponse, err error)

Request

Instantiate the CreateCaOptions struct and set the fields to provide parameter values for the CreateCa method.

Create a CA in your Kubernetes cluster.

The CreateCa options.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-ca" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"display_name\": \"My CA\",
          \"config_override\":{
            \"ca\":{
              \"registry\":{
                \"maxenrollments\": -1,
                \"identities\": [{
                  \"name\": \"admin\",
                  \"pass\": \"password\",
                  \"type\": \"client\",
                  \"affiliation\": \"\",
                  \"attrs\":{
                          \"hf.Registrar.Roles\": \"*\",
                          \"hf.Registrar.DelegateRoles\": \"*\",
                          \"hf.Revoker\": true,
                          \"hf.IntermediateCA\": true,
                          \"hf.GenCRL\": true,
                          \"hf.Registrar.Attributes\": \"*\",
                          \"hf.AffiliationMgr\": true
                  }
                }]
              }
            }
          }
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
        ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
        URL: "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := NewBlockchainV2(options)
    if err != nil {
        return
    }
    
    // Create CA
    var identities []blockchainv2.ConfigCARegistryIdentitiesItem
    svc, err := service.NewConfigCARegistryIdentitiesItem("{User_Name}", "{Secret}", "{Type}")
    if err != nil {
      return //err
    }
    identities = append(identities, *svc)
    registry, err := service.NewConfigCARegistry(-1, identities)
    if err != nil {
      return
    }
    ca_config_create, err := service.NewConfigCACreate(registry)
    if err != nil {
      return
    }
    config_override, err := service.NewCreateCaBodyConfigOverride(ca_config_create)
    if err != nil {
      return
    }
    opts := service.NewCreateCaOptions("{ Display_Name }", config_override)
    result, detailedResponse, err := service.CreateCa(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a CA.

Contains the details of a CA.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

Example responses

Import a CA

Import an existing Certificate Authority (CA) to your IBP console. It is recommended to only import components that were created by this or another IBP console.

Import an existing Certificate Authority (CA) to your IBP console. It is recommended to only import components that were created by this or another IBP console.

POST /ak/api/v2/components/fabric-ca
(blockchain *BlockchainV2) ImportCa(importCaOptions *ImportCaOptions) (result *CaResponse, response *core.DetailedResponse, err error)

Request

Instantiate the ImportCaOptions struct and set the fields to provide parameter values for the ImportCa method.

Import a CA.

The ImportCa options.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/fabric-ca" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"name\": \"My Imported CA\",
          \"api_url\": \"https://n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud:7054\",
          \"operations_url\": \"https://n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud:9443\",
          \"ca_name\": \"ca\",
          \"tlsca_name\": \"tlsca\",
          \"tls_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\",
          \"location\": \"ibmcloud\"
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
        ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
        URL: "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := NewBlockchainV2(options)
    if err != nil {
        return
    }
    
    // Import CA
    opts := service.NewImportCaOptions("{Display_Name}", "{API_URL}", "{CA_Name}", "{TLS_CA_Name}", "{TLS_Cert}")
    result, detailedResponse, err := service.ImportCa(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a CA.

Contains the details of a CA.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

Example responses

Update a CA

Update Kubernetes deployment attributes of a Hyperledger Fabric Certificate Authority (CA) in your cluster.

Update Kubernetes deployment attributes of a Hyperledger Fabric Certificate Authority (CA) in your cluster.

PUT /ak/api/v2/kubernetes/components/fabric-ca/{id}
(blockchain *BlockchainV2) UpdateCa(updateCaOptions *UpdateCaOptions) (result *CaResponse, response *core.DetailedResponse, err error)

Request

Instantiate the UpdateCaOptions struct and set the fields to provide parameter values for the UpdateCa method.

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Update a CA in your Kubernetes cluster. All body fields are optional (only send the fields that you want to change).

The UpdateCa options.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-ca/{Component-ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"resources\":{
            \"ca\":{
              \"requests\":{
                \"cpu\": \"200m\",
                \"memory\":\"256Mi\"
              }
            }
           }
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Update CA
    cpu := "200m"
    memory := "256Mi"
    resourceRequests := blockchainv2.ResourceRequests{Cpu: &cpu, Memory: &memory}
    resourceObject, err := service.NewResourceObject(&resourceRequests)
    if err != nil {
      return
    }
    
    caBodyResources, err := service.NewUpdateCaBodyResources(resourceObject)
    if err != nil {
      return
    }
    
    opts := service.NewUpdateCaOptions("{ CA_Id }")
    opts.SetResources(caBodyResources)
    result, detailedResponse, err := service.UpdateCa(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a CA.

Contains the details of a CA.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Edit data about a CA

Modify local metadata fields of a Certificate Authority (CA). For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the CA.

Modify local metadata fields of a Certificate Authority (CA). For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the CA.

PUT /ak/api/v2/components/fabric-ca/{id}
(blockchain *BlockchainV2) EditCa(editCaOptions *EditCaOptions) (result *CaResponse, response *core.DetailedResponse, err error)

Request

Instantiate the EditCaOptions struct and set the fields to provide parameter values for the EditCa method.

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit local metadata about a CA. All body fields are optional (only send the fields that you want to change).

The EditCa options.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"display_name\": \"My Other CA\",
          \"tags\": [\"fabric-ca\", \"ibm_saas\", \"blue_team\", \"dev\"]
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Edit CA Data
    tags := [4]string{"fabric-ca", "ibm_sass", "blue_team", "dev"}
    opts := service.NewEditCaOptions("{CA_Id}")
    opts.SetCaName("My Ca Edited")
    opts.SetTags(tags[:])
    result, detailedResponse, err := service.EditCa(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a CA.

Contains the details of a CA.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Create a peer

Create a Hyperledger Fabric peer in your Kubernetes cluster.

Create a Hyperledger Fabric peer in your Kubernetes cluster.

POST /ak/api/v2/kubernetes/components/fabric-peer
(blockchain *BlockchainV2) CreatePeer(createPeerOptions *CreatePeerOptions) (result *PeerResponse, response *core.DetailedResponse, err error)

Request

Instantiate the CreatePeerOptions struct and set the fields to provide parameter values for the CreatePeer method.

Create a Hyperledger Fabric peer in your Kubernetes cluster.

The CreatePeer options.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-peer" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"display_name\": \"My Peer\",
          \"msp_id\": \"org2\",
          \"config\": {
            \"enrollment\": {
              \"component\": {
                \"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
                \"caport\": \"7054\",
                \"caname\": \"ca\",
                \"catls\": {
                  \"cacert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
                },
                \"enrollid\": \"admin\",
                \"enrollsecret\": \"password\",
                \"admincerts\": [
                  \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
                ]
              },
              \"tls\": {
                \"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
                \"caport\": \"7054\",
                \"caname\": \"tlsca\",
                \"catls\": {
                  \"cacert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
                },
                \"enrollid\": \"admin\",
                \"enrollsecret\": \"password\",
                \"admincerts\": [
                  \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
                ]
              }
            }
          },
          \"config_override\": {
            \"chaincode\": {
              \"startuptimeout\": \"480s\",
              \"executetimeout\": \"120s\"
            }
          }
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Create Peer
    cacerts := [1]string{"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo"}
    component, err := service.NewMspConfigData(
      "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo",
      "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo",
      cacerts[:])
    if err != nil {
      return
    }
    
    tls, err := service.NewMspConfigData(
      "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo",
      "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo",
      cacerts[:])
    if err != nil {
      return
    }
    
    configObjectMsp, err := service.NewConfigObjectMsp(component, tls)
    if err != nil {
      return
    }
    configObject := blockchainv2.ConfigObject{Msp: configObjectMsp}
    opts := service.NewCreatePeerOptions("{MSP_Name}", "{Peer_Name}", &configObject)
    result, detailedResponse, err := service.CreatePeer(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a peer.

Contains the details of a peer.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

Example responses

Import a peer

Import an existing peer into your IBP console. It is recommended to only import components that were created by this or another IBP console.

Import an existing peer into your IBP console. It is recommended to only import components that were created by this or another IBP console.

POST /ak/api/v2/components/fabric-peer
(blockchain *BlockchainV2) ImportPeer(importPeerOptions *ImportPeerOptions) (result *PeerResponse, response *core.DetailedResponse, err error)

Request

Instantiate the ImportPeerOptions struct and set the fields to provide parameter values for the ImportPeer method.

Import a peer.

The ImportPeer options.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/fabric-peer" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"display_name\": \"My Imported Peer\",
          \"location\": \"ibm cloud\",
          \"api_url\": \"grpcs://n3a3ec3-mypeer.ibp.us-south.containers.appdomain.cloud:7051\",
          \"msp_id\": \"PeerOrg1\",
          \"operations_url\": \"https://n3a3ec3-mypeer.ibp.us-south.containers.appdomain.cloud:9443\",
          \"grpcwp_url\": \"https://n3a3ec3-mypeer-proxy.ibp.us-south.containers.appdomain.cloud:8084\",
          \"tls_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\",
          \"tls_ca_root_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkRpZmZlcmVudCBkYXRhIGhlcmUgaWYgdGhpcyB3YXMgcmVhbAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==\"
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Import Peer
    opts := service.NewImportPeerOptions("{Display_Name}", "{MSP_ID}", "GRPCWP_URL", "{TLS_CA_ROOT_CERT}")
    result, detailedResponse, err := service.ImportPeer(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a peer.

Contains the details of a peer.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

Example responses

Edit data about a peer

Modify local metadata fields of a peer. For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the peer.

Modify local metadata fields of a peer. For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the peer.

PUT /ak/api/v2/components/fabric-peer/{id}
(blockchain *BlockchainV2) EditPeer(editPeerOptions *EditPeerOptions) (result *PeerResponse, response *core.DetailedResponse, err error)

Request

Instantiate the EditPeerOptions struct and set the fields to provide parameter values for the EditPeer method.

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit local metadata about a peer. All body fields are optional (only send the fields that you want to change).

The EditPeer options.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/fabric-peer/{Component-ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"display_name\": \"My Other Peer\",
          \"msp_id\": \"peermsp\",
          \"tags\": [\"fabric-peer\", \"ibm_saas\", \"red_team\", \"prod\"]
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Edit Peer Data
    tags := [4]string{"fabric-peer", "ibm_sass", "red_team", "dev"}
    opts := service.NewEditPeerOptions("{Peer_Id}")
    opts.SetDisplayName("My Other Peer")
    opts.SetMspID("peermsp")
    opts.SetTags(tags[:])
    result, detailedResponse, err := service.EditPeer(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a peer.

Contains the details of a peer.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Update a peer

Update Kubernetes deployment attributes of a Hyperledger Fabric Peer node.

Update Kubernetes deployment attributes of a Hyperledger Fabric Peer node.

PUT /ak/api/v2/kubernetes/components/fabric-peer/{id}
(blockchain *BlockchainV2) UpdatePeer(updatePeerOptions *UpdatePeerOptions) (result *PeerResponse, response *core.DetailedResponse, err error)

Request

Instantiate the UpdatePeerOptions struct and set the fields to provide parameter values for the UpdatePeer method.

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Update a peer in your Kubernetes cluster. All body fields are optional (only send the fields that you want to change).

The UpdatePeer options.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-peer/{Component-ID}" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"resources\":{
            \"peer\":{
              \"requests\":{
                \"cpu\": \"400m\",
                \"memory\":\"800Mi\"
              }
            }
          }
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Update Peer
    cpu := "400m"
    memory := "800Mi"
    resourceRequests := blockchainv2.ResourceRequests{Cpu: &cpu, Memory: &memory}
    resourceObject, err := service.NewResourceObject(&resourceRequests)
    if err != nil {
      return
    }
    
    peerBodyResources := &blockchainv2.PeerResources{Peer: resourceObject}
    
    opts := service.NewUpdatePeerOptions("{Peer_Id}")
    opts.SetResources(peerBodyResources)
    result, detailedResponse, err := service.UpdatePeer(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of a peer.

Contains the details of a peer.

Status Code

  • Request was successful.

  • Request is bad (invalid syntax).

  • Request is unauthorized (invalid credentials).

  • Request is forbidden (credentials lack permission).

  • Component in request was not found.

Example responses

Create an ordering service

Create a Hyperledger Ordering Service (OS) in your Kubernetes cluster. Currently, only raft ordering nodes are supported.

Create a Hyperledger Ordering Service (OS) in your Kubernetes cluster. Currently, only raft ordering nodes are supported.

POST /ak/api/v2/kubernetes/components/fabric-orderer
(blockchain *BlockchainV2) CreateOrderer(createOrdererOptions *CreateOrdererOptions) (result *OrdererResponse, response *core.DetailedResponse, err error)

Request

Instantiate the CreateOrdererOptions struct and set the fields to provide parameter values for the CreateOrderer method.

Create an ordering service in your Kubernetes cluster.

The CreateOrderer options.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-orderer" -H "Content-Type: application/json" -H "Authorization: Bearer {Access-Token}" -d "{
          \"orderer_type\": \"raft\",
          \"msp_id\": \"orderermsp\",
          \"config\": [<ConfigObject-Node-1>, <ConfigObject-Node-2>, <ConfigObject-Node-3>, <ConfigObject-Node-4>, <ConfigObject-Node-5>],
          \"cluster_name\": \"My three Node Raft\",
          \"display_name\": \"ordering service node\"
        }"
  • // Create an authenticator
    authenticator := &core.IamAuthenticator{
      ApiKey: "{API-Key}",
    }
    
    // Create an instance of the "BlockchainV2Options" struct
    options := &blockchainv2.BlockchainV2Options{
      Authenticator: authenticator,
      URL:           "https://{API-Endpoint}",
    }
    
    // Create an instance of the "BlockchainV2" service client.
    service, err := blockchainv2.NewBlockchainV2(options)
    if err != nil {
      return
    }
    
    // Create Ordering Service
    cacert, err := service.NewConfigObjectEnrollmentComponentCatls("LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo")
    if err != nil {
    	return
    }
    
    caTlsCert, err := service.NewConfigObjectEnrollmentTlsCatls("LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo")
    if err != nil {
    	return
    }
    
    enrollmentComponent, err := service.NewConfigObjectEnrollmentComponent("localhost", float64(3000), "myca", cacert, "admin", "password")
    if err != nil {
    	return
    }
    
    tlsEnrollment, err := service.NewConfigObjectEnrollmentTls("localhost", float64(3000), "myca", caTlsCert)
    if err != nil {
    	return
    }
    
    objectEnrollment, err := service.NewConfigObjectEnrollment(enrollmentComponent, tlsEnrollment)
    if err != nil {
    	return
    }
    
    configObject := blockchainv2.ConfigObject{Enrollment: objectEnrollment}
    configObjectArray := [1]blockchainv2.ConfigObject{configObject}
    opts := service.NewCreateOrdererOptions("{Orderer_Type}", "{Msp_Id}", "{Display_Name}", configObjectArray[:])
    opts.SetOrdererType("raft")
    opts.SetMspID("orderermsp")
    opts.SetConfig(configObjectArray[:])
    opts.SetClusterName("My three Node Raft")
    opts.SetDisplayName("ordering service node")
    result, detailedResponse, err := service.CreateOrderer(opts)
    fmt.Println("result:", result)
    fmt.Println("response:", detailedResponse)

Response

Contains the details of an ordering node.