{"id":19728572,"url":"https://github.com/upcloudltd/upcloud-go-api","last_synced_at":"2025-04-30T01:30:53.070Z","repository":{"id":9592440,"uuid":"62697141","full_name":"UpCloudLtd/upcloud-go-api","owner":"UpCloudLtd","description":"Go client for UpCloud's API","archived":false,"fork":false,"pushed_at":"2025-04-28T15:17:27.000Z","size":1797,"stargazers_count":43,"open_issues_count":3,"forks_count":10,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-28T16:24:51.559Z","etag":null,"topics":["api-client","go","go-sdk","golang","upcloud","upcloud-api"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/UpCloudLtd/upcloud-go-api/v8","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UpCloudLtd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-06T06:34:02.000Z","updated_at":"2025-03-27T15:11:41.000Z","dependencies_parsed_at":"2023-10-16T23:37:40.077Z","dependency_job_id":"d029d5b8-8acc-4d7e-b17e-dc17c85576f1","html_url":"https://github.com/UpCloudLtd/upcloud-go-api","commit_stats":{"total_commits":408,"total_committers":34,"mean_commits":12.0,"dds":0.7622549019607843,"last_synced_commit":"bbde1cd00641b606a7f7de4e16478dd5cd95f4f7"},"previous_names":["upcloudltd/upcloud-go-sdk","jalle19/upcloud-go-sdk"],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UpCloudLtd%2Fupcloud-go-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UpCloudLtd%2Fupcloud-go-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UpCloudLtd%2Fupcloud-go-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UpCloudLtd%2Fupcloud-go-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UpCloudLtd","download_url":"https://codeload.github.com/UpCloudLtd/upcloud-go-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251611398,"owners_count":21617399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","go","go-sdk","golang","upcloud","upcloud-api"],"created_at":"2024-11-12T00:03:48.233Z","updated_at":"2025-04-30T01:30:53.064Z","avatar_url":"https://github.com/UpCloudLtd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UpCloud Go API client library\n\n![Build Status](https://github.com/UpCloudLtd/upcloud-go-api/workflows/Upcloud%20go%20api%20test/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/UpCloudLtd/upcloud-go-api)](https://goreportcard.com/report/github.com/UpCloudLtd/upcloud-go-api)\n[![GoDoc](https://godoc.org/github.com/UpCloudLtd/upcloud-go-api?status.svg)](https://godoc.org/github.com/UpCloudLtd/upcloud-go-api)\n\nThis is the official client for interfacing with UpCloud's API using the Go programming language. The features allows for easy and quick development and integration when using Go.\n\n## Usage\n\n### Quickstart\n\nAdd SDK to your project. You will need Go 1.20+ to use it.\n```shell\ngo get github.com/UpCloudLtd/upcloud-go-api/v8\n```\n\nNext in your code:\n```go\nimport (\n\t\"time\"\n\n\t\"github.com/UpCloudLtd/upcloud-go-api/v8/upcloud/client\"\n\t\"github.com/UpCloudLtd/upcloud-go-api/v8/upcloud/service\"\n)\n\nfunc main() {\n\t// First instantiate a client with your username and password.\n\t// `client.New` accepts config functions that allow you to customise the returned client behaviour.\n\t//  Config functions are exported from the `client` package.\n\tclnt := client.New(\"my_username\", \"password123\", client.WithTimeout(time.Second * 30))\n\n\t// Next instantiate new service using the created client\n\tsvc := service.New(clnt)\n\n\t// Validate that everything is set up correctly\n\taccount, err := svc.GetAccount(context.Background())\n}\n```\n\n### Error handling\n\n```go\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\n\t\"github.com/UpCloudLtd/upcloud-go-api/v8/upcloud\"\n\t\"github.com/UpCloudLtd/upcloud-go-api/v8/upcloud/client\"\n\t\"github.com/UpCloudLtd/upcloud-go-api/v8/upcloud/service\"\n)\n\nfunc main() {\n\tsvc := service.New(client.New(\"my_username\", \"password123\"))\n\t_, err := svc.GetAccount(context.Background())\n\n\tif err != nil {\n\t\t// `upcloud.Problem` is the error object returned by all of the `Service` methods.\n\t\t//  You can differentiate between generic connection errors (like the API not being reachable) and service errors, which are errors returned in the response body by the API;\n\t\t//\tthis is useful for gracefully recovering from certain types of errors;\n\t\tvar problem *upcloud.Problem\n\n\t\tif errors.As(err, \u0026problem) {\n\t\t\tfmt.Println(problem.Status)        // HTTP status code returned by the API\n\t\t\tfmt.Print(problem.Title)           // Short, human-readable description of the problem\n\t\t\tfmt.Println(problem.CorrelationID) // Unique string that identifies the request that caused the problem; note that this field is not always populated\n\t\t\tfmt.Println(problem.InvalidParams) // List of invalid request parameters\n\n\t\t\tfor _, invalidParam := range problem.InvalidParams {\n\t\t\t\tfmt.Println(invalidParam.Name)   // Path to the request field that is invalid\n\t\t\t\tfmt.Println(invalidParam.Reason) // Human-readable description of the problem with that particular field\n\t\t\t}\n\n\t\t\t// You can also check against the specific api error codes to programatically react to certain situations.\n\t\t\t// Base `upcloud` package exports all the error codes that API can return.\n\t\t\t// You can check which error code is return in which situation in UpCloud API docs -\u003e https://developers.upcloud.com/1.3\n\t\t\tif problem.ErrorCode() == upcloud.ErrCodeResourceAlreadyExists {\n\t\t\t\tfmt.Println(\"Looks like we don't need to create this\")\n\t\t\t}\n\n\t\t\t// `upcloud.Problem` implements the Error interface, so you can also just use it as any other error\n\t\t\tfmt.Println(fmt.Errorf(\"we got an error from the UpCloud API: %w\", problem))\n\t\t} else {\n\t\t\t// This means you got an error, but it does not come from the API itself. This can happen, for example, if you have some connection issues,\n\t\t\t// or if the UpCloud API is unreachable for some other reason\n\t\t\tfmt.Println(\"We got a generic error!\")\n\t\t}\n\t}\n}\n```\n\n### Packages\n\nUpCloud Go SDK includes the following packages:\n- `upcloud` package - contains type definitions for all UpCloud API objects like servers, storages, load balancers, Kubernetes clusters, errors, etc. It also has a lot of constants that allow you, for example, to compare state, status and other properties of various objects.\n- `client` package - contains functions that allow you to create and customise HTTP client that will be used to make requests to UpCloud API. The returned client does expose some methods for making requests, but you shouldn't really use them directly, client should only be used to instantiate a new `Service`\n- `service` package - contains the `Service` type, which exposes all the methods to interact with UpCloud API. This is the package you will probably use most frequently. All `Service` methods accept `context.Context` as firt parameter. _Most_ `Service` methods accept a `request` object as the second parameter (see package below).\n- `request` package - contains various `request` objects. Those objects should always be used as an argument for a `Service` method and allow you to provide additional params for the request URL or body. For example, when fetching details of a speficic server, you would use a request object to speficy the server UUID. Similarly, when creating server you would use request object to specify server properties, like CPU, memory, OS, login method, etc.\n\n### Examples\n\nAll of these examples assume you already have a service object configured and named `svc`.\n\n#### Retrieving a list of servers\n\nThe following example will retrieve a list of servers the account has access to.\n\n```go\n// Retrieve the list of servers\nservers, err := svc.GetServers(context.Background())\n\nif err != nil {\n\tpanic(err)\n}\n\n// Print the UUID and hostname of each server\nfor _, server := range servers.Servers {\n\tfmt.Println(fmt.Sprintf(\"UUID: %s, hostname: %s\", server.UUID, server.Hostname))\n}\n```\n\n#### Creating a new server\n\nSince the request for creating a new server is asynchronous, the server will report its status as \"maintenance\" until the deployment has been fully completed.\n\n```go\n// Create the server\nserverDetails, err := svc.CreateServer(context.Background(), \u0026request.CreateServerRequest{\n\tZone:             \"fi-hel2\",\n\tTitle:            \"My new server\",\n\tHostname:         \"server.example.com\",\n\tPasswordDelivery: request.PasswordDeliveryNone,\n\tStorageDevices: []request.CreateServerStorageDevice{\n\t\t{\n\t\t\tAction:  request.CreateStorageDeviceActionClone,\n\t\t\tStorage: \"01000000-0000-4000-8000-000020060100\",\n\t\t\tTitle:   \"disk1\",\n\t\t\tSize:    10,\n\t\t\tTier:    upcloud.StorageTierMaxIOPS,\n\t\t},\n\t},\n\tIPAddresses: []request.CreateServerIPAddress{\n\t\t{\n\t\t\tAccess: upcloud.IPAddressAccessPrivate,\n\t\t\tFamily: upcloud.IPAddressFamilyIPv4,\n\t\t},\n\t\t{\n\t\t\tAccess: upcloud.IPAddressAccessPublic,\n\t\t\tFamily: upcloud.IPAddressFamilyIPv4,\n\t\t},\n\t\t{\n\t\t\tAccess: upcloud.IPAddressAccessPublic,\n\t\t\tFamily: upcloud.IPAddressFamilyIPv6,\n\t\t},\n\t},\n})\n\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Println(fmt.Sprintf(\"Server %s with UUID %s created\", serverDetails.Title, serverDetails.UUID))\n\n// Block for up to five minutes until the server has entered the \"started\" state\nerr = svc.WaitForServerState(context.Background(), \u0026request.WaitForServerStateRequest{\n\tUUID:         serverDetails.UUID,\n\tDesiredState: upcloud.ServerStateStarted,\n})\n\nif err != nil {\n\tpanic(err)\n}\n\nfmt.Println(\"Server is now started\")\n```\n\n### Templatizing a server's storage device\n\nIn this example, we assume that there is a server represented by the variable `serverDetails` and that the server state is `stopped`. The next piece of code allows you to templatize the first storage device of the server.\n\n```go\n// Loop through the storage devices\nfor i, storage := range serverDetails.StorageDevices {\n\t// Find the first device\n\tif i == 0 {\n\t\t// Templatize the storage\n\t\tstorageDetails, err := svc.TemplatizeStorage(context.Background(), \u0026request.TemplatizeStorageRequest{\n\t\t\tUUID:  storage.UUID,\n\t\t\tTitle: \"Templatized storage\",\n\t\t})\n\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tfmt.Println(fmt.Sprintf(\"Storage templatized as %s\", storageDetails.UUID))\n\t\tbreak\n\t}\n}\n```\n\n### Create a manual backup\n\nIn this example, we assume that there is a storage device represented by `storageDetails` and that if it is attached to any server, the server is stopped.\n\n```go\nbackupDetails, err := svc.CreateBackup(context.Background(), \u0026request.CreateBackupRequest{\n\tUUID:  storageDetails.UUID,\n\tTitle: \"Backup\",\n})\n\nif err != nil {\n    panic(err)\n}\n\nfmt.Println(fmt.Sprintf(\"Backup of %s created as %s\", storageDetails.UUID, backupDetails.UUID))\n```\n\n### Create a new firewall rule\n\nIn this example, we assume that there is a server represented by the variable `serverDetails`.\n\n```go\nfirewallRule, err := svc.CreateFirewallRule(context.Background(), \u0026request.CreateFirewallRuleRequest{\n\tServerUUID: serverDetails.UUID,\n\tFirewallRule: upcloud.FirewallRule{\n\t\tDirection: upcloud.FirewallRuleDirectionIn,\n\t\tAction:    upcloud.FirewallRuleActionAccept,\n\t\tFamily:    upcloud.IPAddressFamilyIPv4,\n\t\tProtocol:  upcloud.FirewallRuleProtocolTCP,\n\t\tPosition:  1,\n\t\tComment:   \"Accept all TCP input on IPv4\",\n\t},\n})\n\nif err != nil {\n    panic(err)\n}\n```\n\nFor more examples, please consult the service integration test suite (`upcloud/service/service_test.go`).\n\n## License\n\nThis client is distributed under the [MIT License](https://opensource.org/licenses/MIT), see LICENSE.txt for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupcloudltd%2Fupcloud-go-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fupcloudltd%2Fupcloud-go-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupcloudltd%2Fupcloud-go-api/lists"}