mrshah-at-ibm / ibp-go-sdk Goto Github PK

Blockchain Go SDK/Module

GoLang client library to use the IBM Cloud Blockchain Service.

This module will allow you to use native golang functions to leverage the same functionality seen in the IBP APIs

The IBM Cloud Blockchain Go SDK allows developers to programmatically interact with the IBM Cloud Blockchain service.

• An IBM Cloud account.
• An IBM Blockchain Platform Service instance
• An IAM API key to allow the SDK to access your service instance. Create an account level api key here (alternatively you can create a service instance level api key from the IBM cloud UI).
• An installation of Go (version 1.12 or above) on your local machine.

There are a few different ways to download and install the Blockchain Go SDK project for use by your Go application:

Use this command to download and install the Blockchain Go SDK project to allow your Go application to use it:

go get -u github.com/IBM-Blockchain/ibp-go-sdk

If your application is using Go modules, you can add a suitable import to your Go application, like this:

import (
    "github.com/IBM-Blockchain/ibp-go-sdk/blockchainv2"
)

then run go mod tidy to download and install the new dependency and update your Go application's go.mod file.

If your application is using the dep dependency management tool, you can add a dependency to your Gopkg.toml file. Here is an example:

[[constraint]]
  name = "github.com/IBM-Blockchain/ibp-go-sdk/blockchainv2"
  version = "0.0.1"

then run dep ensure.

This section provides general information on how to use the services contained in this SDK.

Each service is implemented in its own package (e.g. blockchainv2). The package will contain a "service client" struct (a client-side representation of the service), as well as an "options" struct that is used to construct instances of the service client.
Here's an example of how to construct an instance of "My Service":

import (
    "github.com/IBM/go-sdk-core/core"
    "github.com/IBM-Blockchain/ibp-go-sdk/blockchainv2"
)

// Create an authenticator.
authenticator := /* create an authenticator - see examples below */

// Create an instance of the "BlockchainV2Options"  struct.
myserviceURL := "https://myservice.cloud.ibm.com/api"
options := &blockchainv2.BlockchainV2Options{
    Authenticator: authenticator,
    URL: myserviceURL,
}

// Create an instance of the "BlockchainV2" service client.
service, err := NewBlockchainV2(options)
if err != nil {
    // handle error
}

// Service operations can now be called using the "service" variable.

Blockchain services use token-based Identity and Access Management (IAM) authentication.

IAM authentication uses an API key to obtain an access token, which is then used to authenticate each API request. Access tokens are valid for a limited amount of time and must be regenerated.

To provide credentials to the SDK, you supply either an IAM service API key or an access token:

• Specify the IAM API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it when necessary.
• Specify the access token if you want to manage the lifecycle yourself. For details, see Authenticating with IAM tokens.

• Supplying the IAM API key and letting the SDK manage the access token for you:

// letting the SDK manage the IAM access token
import (
    "github.com/IBM/go-sdk-core/core"
    "github.com/IBM-Blockchain/ibp-go-sdk/blockchainv2"
)
...
// Create the IAM authenticator.
authenticator := &core.IamAuthenticator{
    ApiKey: "myapikey",
}

// Create the service options struct.
options := &blockchainv2.BlockchainV2Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service, err := blockchainv2.NewBlockchainV2(options)

• Supplying the access token (a bearer token) and managing it yourself:

import (
    "github.com/IBM/go-sdk-core/core"
    "github.com/IBM-Blockchain/ibp-go-sdk/blockchainv2"
)
...
// Create the BearerToken authenticator.
authenticator := &core.BearerTokenAuthenticator{
    BearerToken: "my IAM access token",
}

// Create the service options struct.
options := &blockchainv2.BlockchainV2Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service, err := blockchainv2.NewBlockchainV2(options)

...
// Later when the access token expires, the application must refresh the access token,
// then set the new access token on the authenticator.
// Subsequent request invocations will include the new access token.
authenticator.BearerToken = /* new access token */

For more information on authentication, including the full set of authentication schemes supported by the underlying Go Core library, see this page

For each operation belonging to a service, an "options" struct is defined as a container for the parameters associated with the operation. The name of the struct will be <operation-name>Options and it will contain a field for each operation parameter.
Here's an example of an options struct for the GetComponent operation:

// GetComponentOptions : The GetComponent options.
type GetComponentOptions struct {

    // The id of the resource to retrieve.
    ID *string `json:"resource_id" validate:"required"`

    ...
}

When invoking this operation, the application first creates an instance of the GetComponentOptions struct and then sets the parameter values within it. Along with the "options" struct, a constructor function is also provided.
Here's an example:

options := service.NewGetComponentOptions("resource-id-1")

Then the operation can be called like this:

result, detailedResponse, err := service.GetComponent(options)

This use of the "options" struct pattern (instead of listing each operation parameter within the argument list of the service method) allows for future expansion of the API (within certain guidelines) without impacting applications.

Each service method (operation) will return the following values:

1. result - An operation-specific result (if the operation is defined as returning a result).
2. detailedResponse - An instance of the core.DetailedResponse struct. This will contain the following fields:

• StatusCode - the HTTP status code returned in the response message
• Headers - the HTTP headers returned in the response message
• Result - the operation result (if available). This is the same value returned in the result return value mentioned above.

3. err - An error object. This return value will be nil if the operation was successful, or non-nil if unsuccessful.

1. Here's an example of calling the GetComponent operation which returns an instance of the Resource struct as its result:

// Construct the service instance.
service, err := blockchainv2.NewBlockchainV2(
    &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
    })

// Call the GetComponent operation and receive the returned Resource.
options := service.NewGetComponentOptions("resource-id-1")
result, detailedResponse, err := service.GetComponent(options)

// Now use 'result' which should be an instance of 'Resource'.

2. Here's an example of calling the DeleteResource operation which does not return a response object:

// Construct the service instance.
service, err := blockchainv2.NewBlockchainV2(
    &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
    })

// Call the DeleteResource operation and receive the returned Resource.
options := service.NewDeleteResourceOptions("resource-id-1")
detailedResponse, err := service.DeleteResource(options)

In the case of an error response from the server endpoint, the Blockchain Go SDK will do the following:

1. The service method (operation) will return a non-nil error object. This error object will contain the error message retrieved from the HTTP response if possible, or a generic error message otherwise.
2. The detailedResponse.Result field will contain the unmarshalled response (in the form of a map[string]interface{}) if the operation returned a JSON response.
   This allows the application to examine all of the error information returned in the HTTP response message.
3. The detailedResponse.RawResult field will contain the raw response body as a []byte if the operation returned a non-JSON response.

Here's an example of checking the error object after invoking the GetComponent operation:

// Call the GetComponent operation and receive the returned Resource.
options := service.NewGetComponentOptions("bad-resource-id", "bad-resource-type")
result, detailedResponse, err := service.GetComponent(options)
if err != nil {
    fmt.Println("Error retrieving the resource: ", err.Error())
    fmt.Println("   full error response: ", detailedResponse.Result)
}

Default HTTP headers can be specified by using the SetDefaultHeaders(http.Header) method of the client instance. Once set on the service client, default headers are sent with every outbound request.

The example below sets the header Custom-Header with the value "custom_value" as a default header:

// Construct the service instance.
service, err := blockchainv2.NewBlockchainV2(
    &blockchainv2.BlockchainV2Options{
        Authenticator: authenticator,
    })

customHeaders := http.Header{}
customHeaders.Add("Custom-Header", "custom_value")
service.Service.SetDefaultHeaders(customHeaders)

// "Custom-Header" will now be included with all subsequent requests invoked from "service".

Custom HTTP headers can also be passed with any individual request. To do so, add the headers to the "options" struct passed to the service method.

Here's an example that sets "Custom-Header" on the GetComponentOptions instance and then invokes the GetComponent operation:

// Call the GetComponent operation, passing our Custom-Header.
options := service.NewGetComponentOptions("resource-id-1")
customHeaders := make(map[string]interface{})
customHeaders["Custom-Header"] = "custom_value"
options.SetHeaders(customHeaders)
result, detailedResponse, err := service.GetComponent(options)
// "Custom-Header" will be sent along with the "GetComponent" request.

This module is generated from the OpenAPI (swagger) file that populated the IBP APIs documentation. It is recommended to explore the IBP APIs documentation to find the desired functionality. Then find the corresponding go method and its input struct details in blockchain_v2.go.

This is a note for developers of this repository on how to rebuild the SDK.

• this module was generated/built via the IBM Cloud OpenAPI SDK generator
  • SDK generator overview
  • Configuration option code
  • IBP's OpenAPI source

1. download the latest sdk generator release (should see the java file lib/openapi-sdkgen.jar)
2. clone/download the IBP OpenAPI file
3. build command w/o shell:

java -jar ./lib/openapi-sdkgen.jar generate -g ibm-go -i C:\code\cloud-api-docs\ibp.yaml -o C:\code\openapi-sdkgen\build

The IBM Cloud Blockchain Go SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.