Skip to content

Commit d929c43

Browse files
committed
Fix Markdown lint output
1 parent 593e284 commit d929c43

File tree

1 file changed

+51
-8
lines changed

1 file changed

+51
-8
lines changed

README.md

Lines changed: 51 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,22 +5,27 @@
55
[![Report card](https://goreportcard.com/badge/github.com/cloudfoundry/go-cfclient/v3)](https://goreportcard.com/report/github.com/cloudfoundry/go-cfclient/v3)
66

77
## Overview
8+
89
`go-cfclient` is a go module library to assist you in writing apps that need to interact the [Cloud Foundry](http://cloudfoundry.org)
9-
Cloud Controller [v3 API](https://v3-apidocs.cloudfoundry.org). The v2 API is no longer supported, however if you _really_
10+
Cloud Controller [v3 API](https://v3-apidocs.cloudfoundry.org). The v2 API is no longer supported, however if you **really**
1011
need to use the older API you may use the go-cfclient v2 branch and releases.
1112

12-
__NOTE__ - The v3 version in the main branch is currently under development and may have **breaking changes** until a v3.0.0 release is
13-
cut. Until then, you may want to pin to a specific v3.0.0-alpha.x release.
13+
**NOTE** - The v3 version in the main branch is currently under development and may have **breaking changes** until a v3.0.0 release is
14+
cut. Until then, you may want to pin to a specific v3.0.0-alpha.x release.
1415

1516
## Installation
17+
1618
go-cfclient is compatible with modern Go releases in module mode, with Go installed:
17-
```
19+
20+
```shell
1821
go get github.com/cloudfoundry/go-cfclient/v3
1922
```
23+
2024
Will resolve and add the package to the current development module, along with its dependencies. Eventually this
2125
library will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the Versioning section below.
2226

2327
## Usage
28+
2429
- [Authentication](./README.md#authentication)
2530
- [Resources](./README.md#resources)
2631
- [Filtering](./README.md#filtering)
@@ -30,6 +35,7 @@ library will cut releases that will be tagged with v3.0.0, v3.0.1 etc, see the V
3035
- [Migrating v2 to v3](./README.md#migrating-v2-to-v3)
3136

3237
Using go modules import the client, config and resource packages:
38+
3339
```go
3440
import (
3541
"github.com/cloudfoundry/go-cfclient/v3/client"
@@ -39,61 +45,78 @@ import (
3945
```
4046

4147
### Authentication
48+
4249
Construct a new CF client configuration object. The configuration object configures how the client will authenticate to the
4350
CF API. There are various supported auth mechanisms.
4451

4552
The simplest being - use the existing CF CLI configuration and auth token:
53+
4654
```go
4755
cfg, _ := config.NewFromCFHome()
4856
cf, _ := client.New(cfg)
4957
```
58+
5059
Username and password:
60+
5161
```go
5262
cfg, _ := config.New("https://api.example.org", config.UserPassword("user", "pass"))
5363
cf, _ := client.New(cfg)
5464
```
65+
5566
Client and client secret:
67+
5668
```go
5769
cfg, _ := config.New("https://api.example.org", config.ClientCredentials("cf", "secret"))
5870
cf, _ := client.New(cfg)
5971
```
72+
6073
Client and client assertion:
74+
6175
```go
6276
cfg, _ := config.New("https://api.example.org", config.ClientCredentials("cf",""),config.ClientAssertion("client-assertion-token"))
6377
cf, _ := client.New(cfg)
6478
```
79+
6580
Static OAuth token, which requires both an access and refresh token:
81+
6682
```go
6783
cfg, _ := config.New("https://api.example.org", config.Token(accessToken, refreshToken))
6884
cf, _ := client.New(cfg)
6985
```
86+
7087
Using JWT Bearer Assertion Grant
88+
7189
```go
7290
cfg, _ := config.New("https://api.example.org",config.JWTBearerAssertion("jwt-assertion-token"))
7391
cf, _ := client.New(cfg)
7492
```
93+
7594
For more detailed examples of using the various authentication and configuration options, see the
7695
[auth example](./examples/auth/main.go).
7796

7897
### Resources
98+
7999
The services of a client divide the API into logical chunks and correspond to the structure of the CF API documentation
80-
at https://v3-apidocs.cloudfoundry.org. In other words each major resource type has its own service client that
100+
at [https://v3-apidocs.cloudfoundry.org](https://v3-apidocs.cloudfoundry.org). In other words each major resource type has its own service client that
81101
is accessible via the main client instance.
102+
82103
```go
83104
apps, _ := cf.Applications.ListAll(context.Background(), nil)
84105
for _, app := range apps {
85106
fmt.Printf("Application %s is %s\n", app.Name, app.State)
86107
}
87108
```
109+
88110
All clients and their functions that interact with the CF API live in the `client` package. The client package
89111
is responsible for making HTTP requests using the resources defined in the `resource` package. All generic serializable
90112
resource definitions live in the `resource` package and could be reused with other client's outside this library.
91113

92-
__NOTE__ - Using the context package you can easily pass cancellation signals and deadlines to various client calls
114+
**NOTE** - Using the context package you can easily pass cancellation signals and deadlines to various client calls
93115
for handling a request. In case there is no context available, then `context.Background()` can be used as a starting
94116
point.
95117

96118
### Filtering
119+
97120
This library should support all possible
98121
[filtering combinations that the CF API supports](https://v3-apidocs.cloudfoundry.org/version/3.188.0/index.html#filters),
99122
including those that may not be valid. While the library tries to steer you in a direction that won't allow for invalid
@@ -105,6 +128,7 @@ combinations it's still possible to create filters that are nonsensical. The sup
105128
| String | x | x | | x |
106129

107130
Full filtering example, find all apps with the name of spring-music:
131+
108132
```go
109133
opts := client.NewAppListOptions()
110134
opts.Names.EqualTo("spring-music")
@@ -113,28 +137,33 @@ fmt.Printf("Found %d apps named spring-music\n", len(apps))
113137
```
114138

115139
Find multiple applications with specific names:
140+
116141
```go
117142
opts.Names.EqualTo("credit-processor-service", "credit-processor-ui")
118143
```
119144

120145
Find all apps not named spring-music:
146+
121147
```go
122148
opts.Names.NotEqualTo("spring-music")
123149
```
124150

125151
Find all spring-music apps created within a date range:
152+
126153
```go
127154
opts.Names.EqualTo("spring-music")
128155
opts.CreateAts.After(date1)
129156
opts.CreateAts.Before(date2)
130157
```
131158

132159
### Pagination
160+
133161
All requests for resource collections (apps, orgs, spaces etc) support pagination. Pagination options are described
134162
in the client.ListOptions struct and passed to the list methods directly or as an embedded type of a more specific
135163
list options struct (for example client.AppListOptions).
136164

137165
Example iterating through all apps one page at a time:
166+
138167
```go
139168
opts := client.NewAppListOptions()
140169
for {
@@ -148,9 +177,11 @@ for {
148177
pager.NextPage(opts)
149178
}
150179
```
180+
151181
If you'd rather get _all_ of the resources in one go and not worry about paging, every collection
152182
has a corresponding `All` method that gathers all the resources from every page before returning. While this may be
153183
convenient, this could have negative performance consequences on larger foundations/collections.
184+
154185
```go
155186
opts := client.NewAppListOptions()
156187
apps, _ := cf.Applications.ListAll(context.Background(), opts)
@@ -160,9 +191,11 @@ for _, app := range apps {
160191
```
161192

162193
### Asynchronous Jobs
194+
163195
Some API calls are long-running so immediately return a JobID (GUID) instead of waiting and returning a resource. In
164196
those cases you only know if the job was accepted. You will need to poll the Job API to find out when the job
165197
finishes. There's a `PollComplete` utility function that you can use to block until the job finishes:
198+
166199
```go
167200
jobGUID, err := cf.Manifests.ApplyManifest(context.Background(), spaceGUID, manifest))
168201
if err != nil {
@@ -174,6 +207,7 @@ if err != nil {
174207
return err
175208
}
176209
```
210+
177211
The timeout and polling interval can be configured using the PollingOptions struct.
178212

179213
The PollComplete function will return a nil error if the job completes successfully. If PollComplete
@@ -182,10 +216,12 @@ failed then the job API is queried for the job error which is then returned as a
182216
which can be inspected to find the failure cause.
183217

184218
### Error Handling
219+
185220
All client methods will return a `resource.CloudFoundryError` or sub-type for any response that isn't a 200 level
186221
status code. All CF errors have a corresponding error code and the client uses those codes to construct a specific
187222
client side error type. This allows you to easily branch your logic based off specific API error codes using one of
188223
the many `resource.IsSomeTypeOfError(err error)` functions, for example:
224+
189225
```go
190226
params, err := cf.ServiceCredentialBindings.GetParameters(guid)
191227
if resource.IsServiceFetchBindingParametersNotSupportedError(err) {
@@ -198,7 +234,9 @@ if resource.IsServiceFetchBindingParametersNotSupportedError(err) {
198234
```
199235

200236
### Migrating v2 to v3
237+
201238
A very basic example using the v2 client:
239+
202240
```go
203241
c := &cfclient.Config{
204242
ApiAddress: "https://api.sys.example.com",
@@ -208,10 +246,12 @@ c := &cfclient.Config{
208246
client, _ := cfclient.NewClient(c)
209247
apps, _ := client.ListApps()
210248
for _, a := range apps {
211-
fmt.Println(a.Name)
249+
fmt.Println(a.Name)
212250
}
213251
```
252+
214253
Converted to do the same in the v3 client:
254+
215255
```go
216256
cfg, _ := config.New("https://api.sys.example.org", config.UserPassword("user", "pass"))
217257
client, _ := client.New(cfg)
@@ -220,10 +260,12 @@ for _, app := range apps {
220260
fmt.Println(app.Name)
221261
}
222262
```
263+
223264
If you need to migrate over to the new client iteratively you can do that by referencing both the old and new modules
224265
simultaneously and creating two separate client instances - one for each module version.
225266

226267
Some of the main differences between the old client and the new v3 client include:
268+
227269
- The old v2 client supported most v2 resources and few a v3 resources. The new v3 client supports all v3 resources and
228270
no v2 resources. While most v2 resources are similar to their v3 counterparts, some code changes will need to be made.
229271
- The v2 client had a single type that contained resource functions disambiguated by function name. The v3
@@ -235,6 +277,7 @@ client has a separate client nested under the main client for each resource. For
235277
- The v3 client supports shared access across goroutines.
236278

237279
## Versioning
280+
238281
In general, go-cfclient follows [semver](https://go.dev/doc/modules/version-number) as closely as we can for [tagging
239282
releases](https://go.dev/doc/modules/publishing) of the package. We've adopted the following versioning policy:
240283

@@ -256,7 +299,7 @@ functions should have at least once basic unit test.
256299

257300
### Errors
258301

259-
If the Cloud Foundry error definitions change at <https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml>
302+
If the Cloud Foundry error definitions change at [https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml](https://github.com/cloudfoundry/cloud_controller_ng/blob/master/vendor/errors/v2.yml)
260303
then the error predicate functions in this package need to be regenerated.
261304

262305
To do this, simply use Go to regenerate the code:

0 commit comments

Comments
 (0)