github.com/jghiloni/cli@v6.28.1-0.20170628223758-0ce05fe032a2+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  // For Example:
    21  //   Method Name: GetApplication
    22  //   Endpoint: /v3/applications/:guid
    23  //   Action Name: Get
    24  //   Top Level Endpoint: applications
    25  //   Return Value: Application
    26  //
    27  //   Method Name: GetServiceInstances
    28  //   Endpoint: /v3/service_instances
    29  //   Action Name: Get
    30  //   Top Level Endpoint: service_instances
    31  //   Return Value: []ServiceInstance
    32  //
    33  //   Method Name: GetSpaceServiceInstances
    34  //   Endpoint: /v3/spaces/:guid/service_instances
    35  //   Action Name: Get
    36  //   Top Level Endpoint: spaces
    37  //   Return Value: []ServiceInstance
    38  //
    39  //   Method Name: CreateApplicationTask
    40  //   Endpoint: /v3/apps/:application_guid/task
    41  //   Action Name: Post
    42  //   Top Level Endpoint: apps
    43  //   Return Value: []Task
    44  //
    45  // Use the following table to determine which HTTP Command equates to which
    46  // Action Name:
    47  //   HTTP Command -> Action Name
    48  //   POST -> Create
    49  //   GET -> Get
    50  //   PUT -> Update
    51  //   DELETE -> Delete
    52  //
    53  // Method Locations
    54  //
    55  // Methods exist in the same file as their return type, regardless of which
    56  // endpoint they use.
    57  //
    58  // Error Handling
    59  //
    60  // All error handling that requires parsing the error_code/code returned back
    61  // from the Cloud Controller should be placed in the errorWrapper. Everything
    62  // else can be handled in the individual operations. All parsed cloud
    63  // controller errors should exist in errors.go, all generic HTTP errors should
    64  // exist in the cloudcontroller's errors.go. Errors related to the individaul
    65  // operation should exist at the top of that operation's file.
    66  package ccv3
    67  
    68  import (
    69  	"fmt"
    70  	"runtime"
    71  
    72  	"code.cloudfoundry.org/cli/api/cloudcontroller"
    73  	"code.cloudfoundry.org/cli/api/cloudcontroller/ccv3/internal"
    74  )
    75  
    76  // Warnings are a collection of warnings that the Cloud Controller can return
    77  // back from an API request.
    78  type Warnings []string
    79  
    80  // Client can be used to talk to a Cloud Controller's V3 Endpoints.
    81  type Client struct {
    82  	APIInfo
    83  	cloudControllerURL string
    84  
    85  	connection cloudcontroller.Connection
    86  	router     *internal.Router
    87  	userAgent  string
    88  	wrappers   []ConnectionWrapper
    89  }
    90  
    91  // Config allows the Client to be configured
    92  type Config struct {
    93  	// AppName is the name of the application/process using the client.
    94  	AppName string
    95  
    96  	// AppVersion is the version of the application/process using the client.
    97  	AppVersion string
    98  
    99  	// // JobPollingTimeout is the maximum amount of time a job polls for.
   100  	// JobPollingTimeout time.Duration
   101  
   102  	// // JobPollingInterval is the wait time between job polls.
   103  	// JobPollingInterval time.Duration
   104  
   105  	// Wrappers that apply to the client connection.
   106  	Wrappers []ConnectionWrapper
   107  }
   108  
   109  // NewClient returns a new Client.
   110  func NewClient(config Config) *Client {
   111  	userAgent := fmt.Sprintf("%s/%s (%s; %s %s)", config.AppName, config.AppVersion, runtime.Version(), runtime.GOARCH, runtime.GOOS)
   112  	return &Client{
   113  		userAgent: userAgent,
   114  		wrappers:  append([]ConnectionWrapper{newErrorWrapper()}, config.Wrappers...),
   115  	}
   116  }