cloudant-go-sdk

module
v0.0.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 12, 2020 License: Apache-2.0

README

Build Status

IBM Cloudant Go SDK Version 0.0.27

Go client library to interact with the IBM Cloudant APIs.

Disclaimer: this SDK is being released initially as a pre-release version. Changes might occur which impact applications that use this SDK.

Table of Contents

Overview

The IBM Cloudant Go SDK allows developers to programmatically interact with IBM Cloudant with the help of the cloudantv1 package.

Features

The purpose of this Go SDK is to wrap most of the HTTP request APIs provided by Cloudant and supply other functions to ease the usage of Cloudant. Moreover, it has limited support for CouchDB as well. This SDK should make life easier for programmers to do what’s really important for them: develop.

Reasons why you should consider using Cloudant Go SDK in your project:

  • Supported by IBM Cloudant.
  • Includes all the most popular and latest supported endpoints for applications.
  • Handles the authentication.
  • Familiar user experience of IBM Cloud SDKs.
  • HTTP2 support for higher performance connections to IBM Cloudant.
  • Perform requests synchronously.
  • Safe for concurrent use by multiple goroutines.
  • Transparently compresses request and response bodies.

Prerequisites

  • An IBM Cloud account.
  • An IAM API key to allow the SDK to access your account. Create one here.
  • Go version 1.13 or above.

Installation

The current version of this SDK: 0.0.27

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

go get command

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

go get -u github.com/IBM/cloudant-go-sdk/cloudantv1
Go modules

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

import (
  "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

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

dep dependency manager

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/cloudant-go-sdk"
  version = "0.0.27"

then run dep ensure.

Authentication

This library requires some of your Cloudant service credentials to authenticate with your account.

  1. IAM, BASIC or NOAUTH authentication type.
    1. IAM authentication is highly recommended when your back-end database server is Cloudant. This authentication type requires a server-generated apikey instead of a user-given password.
    2. Basic (or legacy) authentication is a fallback for both Cloudant and Apache CouchDB back-end database servers. This authentication type requires the good old username and password credentials.
    3. Noauth authentication does not need any credentials. Note that this authentication type will only work for queries against a database with read access for everyone.
  2. The service url.

There are several ways to set these properties:

  1. As environment variables
  2. The programmatic approach
  3. With an external credentials file
Authenticate with environment variables
IAM authentication

For Cloudant IAM authentication set the following environmental variables by replacing <url> and <apikey> with your proper service credentials. There is no need to set CLOUDANT_AUTH_TYPE to IAM because it is the default.

CLOUDANT_URL=<url>
CLOUDANT_APIKEY=<apikey>
Basic authentication

For Basic authentication set the following environmental variables by replacing <url>, <username> and <password> with your proper service credentials.

CLOUDANT_AUTH_TYPE=BASIC
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>

Note: We recommend using IAM for Cloudant and Basic for CouchDB authentication.

Authenticate with external configuration

To use an external configuration file, the Cloudant API docs, or the general SDK usage information will guide you.

Authenticate programmatically

To learn more about how to use programmatic authentication, see the related documentation in the Cloudant API docs or in the Go SDK Core document about authentication.

Code examples

The code examples below will follow the authentication with environment variables.

1. Retrieve information from an existing database

This example code gathers some information about an existing database hosted on the https://examples.cloudant.com/ service url. To do this, you need to extend your environment variables with the service url and authentication type to use NOAUTH authentication while reaching the animaldb database. This step is necessary for the SDK to distinguish the EXAMPLES custom service name from the default service name which is CLOUDANT.

EXAMPLES_URL=https://examples.cloudant.com
EXAMPLES_AUTH_TYPE=NOAUTH

Once the environment variables are set, you can try out the code examples.

package main

import (
	"encoding/json"
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
)

func main() {
	// 1. Create a Cloudant client with "EXAMPLES" service name ============
	client, err := cloudantv1.NewCloudantV1UsingExternalConfig(
		&cloudantv1.CloudantV1Options{
			ServiceName: "EXAMPLES",
		},
	)
	if err != nil {
		panic(err)
	}
	// 2. Get server information ===========================================
	serverInformationResult, _, err := client.GetServerInformation(
		client.NewGetServerInformationOptions(),
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Server Version: %s\n", *serverInformationResult.Version)
	// 3. Get database information for "animaldb" ==========================
	dbName := "animaldb"
	databaseInformationResult, _, err := client.GetDatabaseInformation(
		client.NewGetDatabaseInformationOptions(
			dbName,
		),
	)
	if err != nil {
		panic(err)
	}
	// 4. Show document count in database ==================================
	fmt.Printf("Document count in \"%s\" database is %d.\n",
		*databaseInformationResult.DbName,
		*databaseInformationResult.DocCount)
	// 5. Get zebra document out of the database by document id ============
	documentAboutZebraResult, _, err := client.GetDocument(
		client.NewGetDocumentOptions(
			dbName,
			"zebra",
		),
	)
	if err != nil {
		panic(err)
	}
	// 6. Print out the Document content ===================================
	aboutZebraBuffer, _ := json.MarshalIndent(documentAboutZebraResult, "", "  ")
	fmt.Println(string(aboutZebraBuffer))
}

The result of the code is similar to the following output.

Server Version: 2.1.1
Document count in "animaldb" database is 11.
{
  "_id": "zebra",
  "_rev": "3-750dac460a6cc41e6999f8943b8e603e",
  "class": "mammal",
  "diet": "herbivore",
  "max_length": 2.5,
  "max_weight": 387,
  "min_length": 2,
  "min_weight": 175,
  "wiki_page": "http://en.wikipedia.org/wiki/Plains_zebra"
}
2. Create your own database and add a document

Now comes the exciting part of creating your own orders database and adding a document about Bob Smith with your own IAM or Basic service credentials.

package main

import (
	"encoding/json"
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
)

func main() {
	// 1. Create a client with `CLOUDANT` default service name =============
	client, err := cloudantv1.NewCloudantV1UsingExternalConfig(
		&cloudantv1.CloudantV1Options{},
	)
	if err != nil {
		panic(err)
	}

	// 2. Create a database ================================================
	exampleDbName := "orders"

	putDatabaseResult, putDatabaseResponse, err := client.PutDatabase(
		client.NewPutDatabaseOptions(exampleDbName),
	)
	if err != nil {
		if putDatabaseResponse.StatusCode == 412 {
			fmt.Printf("Cannot create \"%s\" database, it already exists.\n",
				exampleDbName)
		} else {
			panic(err)
		}
	}

	if putDatabaseResult != nil && *putDatabaseResult.Ok {
		fmt.Printf("\"%s\" database created.\n", exampleDbName)
	}

	// 3. Create a document ================================================
	// 3.1. Create a document object with "example" id
	exampleDocID := "example"
	exampleDocument := cloudantv1.Document{
		ID: &exampleDocID,
	}

	// 3.2. Add "name" and "joined" fields to the document
	exampleDocument.SetProperty("name", "Bob Smith")
	exampleDocument.SetProperty("joined", "2019-01-24T10:42:99.000Z")

	// 3.3. Set the options to get the document out of the database if it exists
	getDocumentOptions := client.NewGetDocumentOptions(
		exampleDbName,
		exampleDocID,
	)

	// 3.4. Check the document existence in the database
	documentInfo, getDocumentResponse, err := client.GetDocument(
		getDocumentOptions,
	)
	if err != nil {
		if getDocumentResponse.StatusCode == 404 {
			// Document does not exist in database
		} else {
			panic(err)
		}
	}

	// 3.5. If it previously existed in the database, set revision of exampleDocument to the latest
	if documentInfo != nil {
		exampleDocument.Rev = documentInfo.Rev
		fmt.Printf("The document revision for \"%s\"  is set to \"%s\".\n",
			exampleDocID,
			*documentInfo.Rev)
	}

	// 3.6. Save the document in the database
	postDocumentOption := client.NewPostDocumentOptions(
		exampleDbName,
	).SetDocument(&exampleDocument)

	postDocumentResult, _, err := client.PostDocument(postDocumentOption)
	if err != nil {
		panic(err)
	}

	// 3.7. Keep track of the revision number from the `example` document object
	exampleDocument.Rev = postDocumentResult.Rev

	// 3.8. Print out the document content
	exampleDocumentContent, _ := json.MarshalIndent(exampleDocument, "", "  ")
	fmt.Printf("You have created the document:\n%s\n", string(exampleDocumentContent))
}

The result of the code is similar to the following output.

"orders" database created.
You have created the document:
{
  "_id": "example",
  "_rev": "1-2c3b9502ed7c4a41d35c92bcf734869c",
  "joined": "2019-01-24T10:42:99.000Z",
  "name": "Bob Smith"
}
3. Update your previously created document

Note: this example code assumes that you have created both the orders database and the example document by running this previous example code successfully, otherwise you get the Cannot update document because either "orders" database or "example" document was not found. message.

package main

import (
	"encoding/json"
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
)

func main() {
	// 1. Create a client with `CLOUDANT` default service name =============
	client, err := cloudantv1.NewCloudantV1UsingExternalConfig(
		&cloudantv1.CloudantV1Options{},
	)
	if err != nil {
		panic(err)
	}

	// 2. Update the document ==============================================
	exampleDbName := "orders"
	exampleDocID := "example"

	// 2.1. Get the document if it previously existed in the database
	document, getDocumentResponse, err := client.GetDocument(
		client.NewGetDocumentOptions(
			exampleDbName,
			exampleDocID,
		),
	)
	if err != nil {
		if getDocumentResponse.StatusCode == 404 {
			fmt.Printf("Cannot update document because "+
				"either \"%s\"  database or \"%s\" document was not found.\n",
				exampleDbName,
				exampleDocID)
		} else {
			panic(err)
		}
	}

	if document != nil {
		// 2.2. Make some modifiction in the document content
		// 2.2.1. Add Bob Smith's address to the document
		document.SetProperty("address", "19 Front Street, Darlington, DL5 1TY")
		// 2.2.2. Remove the joined property from document object
		delete(document.GetProperties(), "joined")

		// 2.3. Update the document in the database
		postDocumentOption := client.NewPostDocumentOptions(
			exampleDbName,
		).SetDocument(document)

		postDocumentResult, _, err := client.PostDocument(
			postDocumentOption,
		)
		if err != nil {
			panic(err)
		}

		// 2.4. Keep track the revision number of the document object
		document.Rev = postDocumentResult.Rev

		// 2.5. Print out the new document content
		documentContent, _ := json.MarshalIndent(document, "", "  ")
		fmt.Printf("You have updated the document:\n%s\n", string(documentContent))
	}
}

The result of the code is similar to the following output.

You have updated the document:
{
  "_id": "example",
  "_rev": "2-6cc06e9484d776322f7e697c03fb23f7",
  "address": "19 Front Street, Darlington, DL5 1TY",
  "name": "Bob Smith"
}
4. Delete your previously created document

Note: this example code assumes that you have created both the orders database and the example document by running this previous example code successfully, otherwise you get the Cannot delete document because either "orders" database or "example" document was not found. message.

package main

import (
	"fmt"

	"github.com/IBM/cloudant-go-sdk/cloudantv1"
)

func main() {

	// 1. Create a client with `CLOUDANT` default service name =============
	client, err := cloudantv1.NewCloudantV1UsingExternalConfig(
		&cloudantv1.CloudantV1Options{},
	)
	if err != nil {
		panic(err)
	}

	// 2. Delete the document ==============================================
	exampleDbName := "orders"
	exampleDocID := "example"

	// 2.1. Get the document if it previously existed in the database
	document, getDocumentResponse, err := client.GetDocument(
		client.NewGetDocumentOptions(
			exampleDbName,
			exampleDocID,
		),
	)
	if err != nil {
		if getDocumentResponse.StatusCode == 404 {
			fmt.Printf("Cannot delete document because "+
				"either \"%s\" database or \"%s\" document was not found.\n",
				exampleDbName,
				exampleDocID)
		} else {
			panic(err)
		}
	}
	// 2.2. Use its latest revision to delete
	if document != nil {
		deleteDocumentResult, _, err := client.DeleteDocument(
			client.NewDeleteDocumentOptions(
				exampleDbName,
				*document.ID,
			).SetRev(*document.Rev),
		)
		if err != nil {
			panic(err)
		}

		if *deleteDocumentResult.Ok {
			fmt.Println("You have deleted the document.")
		}
	}
}

The result of the code is the following output.

You have deleted the document.

Error handling

For sample code on handling errors, please see Cloudant API docs.

Using the SDK

For general SDK usage information, please see this link.

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question on Stack Overflow.

Issues

If you encounter an issue with the project, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible that someone has already reported the problem.

Further resources

Open source @ IBM

Find more open source projects on the IBM Github Page.

Contributing

See CONTRIBUTING.

License

This SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.

Directories

Path Synopsis
Package cloudantv1 : Operations and models for the CloudantV1 service
 Package cloudantv1 : Operations and models for the CloudantV1 service
examples
src/create_db_and_doc command
src/delete_doc command
src/get_info_from_existing_database command
src/update_doc command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.