github.com/ablease/cli@v6.37.1-0.20180613014814-3adbb7d7fb19+incompatible/api/cloudcontroller/ccv3/client.go (about) 1 // Package ccv3 represents a Cloud Controller V3 client. 2 // 3 // These sets of packages are still under development/pre-pre-pre...alpha. Use 4 // at your own risk! Functionality and design may change without warning. 5 // 6 // It is currently designed to support Cloud Controller API 3.0.0. However, it 7 // may include features and endpoints of later API versions. 8 // 9 // For more information on the Cloud Controller API see 10 // https://apidocs.cloudfoundry.org/ 11 // 12 // Method Naming Conventions 13 // 14 // The client takes a '<Action Name><Top Level Endpoint><Return Value>' 15 // approach to method names. If the <Top Level Endpoint> and <Return Value> 16 // are similar, they do not need to be repeated. If a GUID is required for the 17 // <Top Level Endpoint>, the pluralization is removed from said endpoint in the 18 // method name. 19 // 20 // Additionally, if the endpoint is an "action" endpoint, do not include the 21 // word "Action" in the method name. 22 // 23 // For Example: 24 // Method Name: GetApplication 25 // Endpoint: /v3/applications/:guid 26 // Action Name: Get 27 // Top Level Endpoint: applications 28 // Return Value: Application 29 // 30 // Method Name: GetServiceInstances 31 // Endpoint: /v3/service_instances 32 // Action Name: Get 33 // Top Level Endpoint: service_instances 34 // Return Value: []ServiceInstance 35 // 36 // Method Name: GetSpaceServiceInstances 37 // Endpoint: /v3/spaces/:guid/service_instances 38 // Action Name: Get 39 // Top Level Endpoint: spaces 40 // Return Value: []ServiceInstance 41 // 42 // Method Name: CreateApplicationTask 43 // Endpoint: /v3/apps/:application_guid/task 44 // Action Name: Post 45 // Top Level Endpoint: apps 46 // Return Value: Task 47 // 48 // Use the following table to determine which HTTP Command equates to which 49 // Action Name: 50 // HTTP Command -> Action Name 51 // POST -> Create OR Update* 52 // GET -> Get 53 // PUT -> Update 54 // DELETE -> Delete 55 // PATCH -> Update 56 // 57 // * - In some cases POSTs are updating resources, in these cases the method 58 // should be called Update, not Create. 59 // 60 // Method Locations 61 // 62 // Methods exist in the same file as their return type, regardless of which 63 // endpoint they use. 64 // 65 // Error Handling 66 // 67 // All error handling that requires parsing the error_code/code returned back 68 // from the Cloud Controller should be placed in the errorWrapper. Everything 69 // else can be handled in the individual operations. All parsed cloud 70 // controller errors should exist in errors.go, all generic HTTP errors should 71 // exist in the cloudcontroller's errors.go. Errors related to the individual 72 // operation should exist at the top of that operation's file. 73 package ccv3 74 75 import ( 76 "fmt" 77 "runtime" 78 "time" 79 80 "code.cloudfoundry.org/cli/api/cloudcontroller" 81 "code.cloudfoundry.org/cli/api/cloudcontroller/ccv3/internal" 82 ) 83 84 // Warnings are a collection of warnings that the Cloud Controller can return 85 // back from an API request. 86 type Warnings []string 87 88 // Client can be used to talk to a Cloud Controller's V3 Endpoints. 89 type Client struct { 90 Info 91 cloudControllerURL string 92 93 connection cloudcontroller.Connection 94 router *internal.Router 95 userAgent string 96 wrappers []ConnectionWrapper 97 98 jobPollingInterval time.Duration 99 jobPollingTimeout time.Duration 100 } 101 102 // Config allows the Client to be configured 103 type Config struct { 104 // AppName is the name of the application/process using the client. 105 AppName string 106 107 // AppVersion is the version of the application/process using the client. 108 AppVersion string 109 110 // JobPollingTimeout is the maximum amount of time a job polls for. 111 JobPollingTimeout time.Duration 112 113 // JobPollingInterval is the wait time between job polls. 114 JobPollingInterval time.Duration 115 116 // Wrappers that apply to the client connection. 117 Wrappers []ConnectionWrapper 118 } 119 120 // NewClient returns a new Client. 121 func NewClient(config Config) *Client { 122 userAgent := fmt.Sprintf("%s/%s (%s; %s %s)", config.AppName, config.AppVersion, runtime.Version(), runtime.GOARCH, runtime.GOOS) 123 return &Client{ 124 userAgent: userAgent, 125 jobPollingInterval: config.JobPollingInterval, 126 jobPollingTimeout: config.JobPollingTimeout, 127 wrappers: append([]ConnectionWrapper{newErrorWrapper()}, config.Wrappers...), 128 } 129 }