# softlayer-go [![Build Status](https://travis-ci.org/softlayer/softlayer-go.svg?branch=master)](https://travis-ci.org/softlayer/softlayer-go) [![GoDoc](https://godoc.org/github.com/softlayer/softlayer-go?status.svg)](https://godoc.org/github.com/softlayer/softlayer-go) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) ![Tests](https://github.com/softlayer/softlayer-go/workflows/Tests/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/softlayer/softlayer-go/badge.svg?branch=master)](https://coveralls.io/github/softlayer/softlayer-go?branch=master) The Official and Complete SoftLayer API Client for Golang (the Go programming language). ## Introduction This library contains a complete implementation of the SoftLayer API for client application development in the Go programming language. Code for each API data type and service method is pre-generated, using the SoftLayer API metadata endpoint as input, thus ensuring 100% coverage of the API right out of the gate. It was designed to feel as natural as possible for programmers familiar with other popular SoftLayer SDKs, and attempts to minimize unnecessary boilerplate and type assertions where possible. ## Usage ### Basic example: Three easy steps: ```go // 1. Create a session sess := session.New(username, apikey) // 2. Get a service accountService := services.GetAccountService(sess) // 3. Invoke a method: account, err := accountService.GetObject() ``` [More examples](https://github.com/softlayer/softlayer-go/tree/master/examples) ### Sessions In addition to the example above, sessions can also be created using values set in the environment, or from the local configuration file (i.e. ~/.softlayer): ```go sess := session.New() ``` In this usage, the username, API key, and endpoint are read from specific environment variables, then the local configuration file (i.e. ~/.softlayer). First match ends the search: * _Username_ 1. environment variable `SL_USERNAME` 1. environment variable `SOFTLAYER_USERNAME` 1. local config `username`. * _API Key_ 1. environment variable `SL_API_KEY` 1. environment variable `SOFTLAYER_API_KEY` 1. local config `api_key`. * _Endpoint_ 1. environment variable `SL_ENDPOINT_URL` 1. environment variable `SOFTLAYER_ENDPOINT_URL` 1. local config `endpoint_url`. * _Timeout_ 1. environment variable `SL_TIMEOUT` 1. environment variable `SOFTLAYER_TIMEOUT` 1. local config `timeout`. *Note:* Endpoint defaults to `https://api.softlayer.com/rest/v3` if not configured through any of the above methods. Timeout defaults to 120 seconds. Example of the **~/.softlayer** local configuration file: ``` [softlayer] username = api_key = endpoint_url = timeout = ``` ### Instance methods To call a method on a specific instance, set the instance ID before making the call: ```go service := services.GetUserCustomerService(sess) service.Id(6786566).GetObject() ``` ### Passing Parameters All non-slice method parameters are passed as pointers. This is to allow for optional values to be omitted (by passing `nil`) ```go guestId := 123456 userCustomerService.RemoveVirtualGuestAccess(&guestId) ``` For convenience, a set of helper functions exists that allocate storage for a literal and return a pointer. The above can be refactored to: ```go userCustomerService.RemoveVirtualGuestAccess(sl.Int(123456)) ``` ### Using datatypes A complete library of SoftLayer API data type structs exists in the `datatypes` package. Like method parameters, all non-slice members are declared as pointers. This has the advantage of permitting updates without re-sending the complete data structure (since `nil` values are omitted from the resulting JSON). Use the same set of helper functions to assist in populating individual members. ```go package main import ( "fmt" "log" "github.com/softlayer/softlayer-go/datatypes" "github.com/softlayer/softlayer-go/services" "github.com/softlayer/softlayer-go/session" "github.com/softlayer/softlayer-go/sl" ) func main() { sess := session.New() // See above for details about creating a new session // Get the Virtual_Guest service service := services.GetVirtualGuestService(sess) // Create a Virtual_Guest struct as a template vGuestTemplate := datatypes.Virtual_Guest{ // Set Creation values - use helpers from the sl package to set pointer values. // Unset (nil) values are not sent Hostname: sl.String("sample"), Domain: sl.String("example.com"), MaxMemory: sl.Int(4096), StartCpus: sl.Int(1), Datacenter: &datatypes.Location{Name: sl.String("wdc01")}, OperatingSystemReferenceCode: sl.String("UBUNTU_LATEST"), LocalDiskFlag: sl.Bool(true), } // Tell the API to create the virtual guest newGuest, err := service.CreateObject(&vGuestTemplate) // optional error checking... if err != nil { log.Fatal(err) } // Print the ID of the new guest. Don't forget to dereference fmt.Printf("New guest %d created", *newGuest.Id) } ``` ### Object Masks, Filters, Result Limits Object masks, object filters, and pagination (limit and offset) can be set by calling the `Mask()`, `Filter()`, `Limit()` and `Offset()` service methods prior to invoking an API method. For example, to set an object mask and filter that will be applied to the results of the Account.GetObject() method: ```go accountService := services.GetAccountService(sess) accountService. Mask("id;hostname"). Filter(`{"virtualGuests":{"domain":{"operation":"example.com"}}}`). GetObject() ``` The mask and filter are applied to the current request only, and reset after the method returns. To preserve these options for future requests, save the return value: ```go accountServiceWithMaskAndFilter = accountService.Mask("id;hostname"). Filter(`{"virtualGuests":{"domain":{"operation":"example.com"}}}`) ``` Result limits are specified as separate `Limit` and `Offset` values: ```go accountService. Offset(100). // start at the 100th element in the list Limit(25). // limit to 25 results GetVirtualGuests() ``` #### Filter Builder There is also a **filter builder** you can use to create a _Filter_ instead of writing out the raw string: ```go // requires importing the filter package accountServiceWithMaskAndFilter = accountService. Mask("id;hostname"). Filter(filter.Path("virtualGuests.domain").Eq("example.com").Build()) ``` You can also create a filter incrementally: ```go // Create initial filters filters := filter.New( filter.Path("virtualGuests.hostname").StartsWith("KM078"), filter.Path("virtualGuests.id").NotEq(12345), ) // .... // Later, append another filter filters = append(filters, filter.Path("virtualGuests.domain").Eq("example.com")) accountServiceWithMaskAndFilter = accountService. Mask("id;hostname"). Filter(filters.Build()) ``` Or you can build all those filters in one step: ```go // Create initial filters filters := filter.Build( filter.Path("virtualGuests.hostname").StartsWith("KM078"), filter.Path("virtualGuests.id").NotEq(12345), filter.Path("virtualGuests.domain").Eq("example.com"), ) accountServiceWithMaskAndFilter = accountService. Mask("id;hostname").Filter(filters) ``` See _filter/filters.go_ for the full range of operations supported. The file at _examples/filters.go_ will show additional examples. Also, [this is a good article](https://sldn.softlayer.com/article/object-filters) that describes SoftLayer filters at length. ### Handling Errors For any error that occurs within one of the SoftLayer API services, a custom error type is returned, with individual fields that can be parsed separately. ```go _, err := service.Id(0). // invalid object ID GetObject() if err != nil { // Note: type assertion is only necessary for inspecting individual fields apiErr := err.(sl.Error) fmt.Printf("API Error:") fmt.Printf("HTTP Status Code: %d\n", apiErr.StatusCode) fmt.Printf("API Code: %s\n", apiErr.Exception) fmt.Printf("API Error: %s\n", apiErr.Message) } ``` Note that `sl.Error` implements the standard `error` interface, so it can be handled like any other error, if the above granularity is not needed: ```go _, err := service.GetObject() if err != nil { fmt.Println("Error during processing: ", err) } ``` ### Session Options To set a different endpoint (e.g., the backend network endpoint): ```go session.Endpoint = "https://api.service.softlayer.com/rest/v3" ``` To enable debug output: ```go session.Debug = true ``` By default, the debug output is sent to standard output. You can customize this by setting up your own logger: ```go import "github.com/softlayer/softlayer-go/session" session.Logger = log.New(os.Stderr, "[CUSTOMIZED] ", log.LstdFlags) ``` You can also tell the session to retry the api requests if there is a timeout error: ```go // Specify how many times to retry the request, the request timeout, and how much time to wait // between retries. services.GetVirtualGuestService( sess.SetTimeout(900).SetRetries(2).SetRetryWait(3) ).GetObject(...) ``` ### Password-based authentication Password-based authentication (via requesting a token from the API) is only supported when talking to the API using the XML-RPC transport protocol. To use the XML-RPC protocol, simply specify an XML-RPC endpoint url: ```go func main() { // Create a session specifying an XML-RPC endpoint url. sess := &session.Session{ Endpoint: "https://api.softlayer.com/xmlrpc/v3", } // Get a token from the api using your username and password userService := services.GetUserCustomerService(sess) token, err := userService.GetPortalLoginToken(username, password, nil, nil) if err != nil { log.Fatal(err) } // Add user id and token to the session. sess.UserId = *token.UserId sess.AuthToken = *token.Hash // You have a complete authenticated session now. // Call any api from this point on as normal... keys, err := userService.Id(sess.UserId).GetApiAuthenticationKeys() if err != nil { log.Fatal(err) } log.Println("API Key:", *keys[0].AuthenticationKey) } ``` ## Development ### Setup To get _softlayer-go_: ``` go get github.com/softlayer/softlayer-go/... ``` ### Build ``` make ``` ### Test ``` make test ``` ### Updating dependencies ``` make update_deps ``` ## Copyright This software is Copyright (c) 2016 IBM Corp. See the bundled LICENSE file for more information.