README.md
1# go-autorest
2
3[](https://godoc.org/github.com/Azure/go-autorest/autorest)
4[](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=625&branchName=master)
5[](https://goreportcard.com/report/Azure/go-autorest)
6
7Package go-autorest provides an HTTP request client for use with [Autorest](https://github.com/Azure/autorest.go)-generated API client packages.
8
9An authentication client tested with Azure Active Directory (AAD) is also
10provided in this repo in the package
11`github.com/Azure/go-autorest/autorest/adal`. Despite its name, this package
12is maintained only as part of the Azure Go SDK and is not related to other
13"ADAL" libraries in [github.com/AzureAD](https://github.com/AzureAD).
14
15## Overview
16
17Package go-autorest implements an HTTP request pipeline suitable for use across
18multiple goroutines and provides the shared routines used by packages generated
19by [Autorest](https://github.com/Azure/autorest.go).
20
21The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending,
22and Responding. A typical pattern is:
23
24```go
25 req, err := Prepare(&http.Request{},
26 token.WithAuthorization())
27
28 resp, err := Send(req,
29 WithLogging(logger),
30 DoErrorIfStatusCode(http.StatusInternalServerError),
31 DoCloseIfError(),
32 DoRetryForAttempts(5, time.Second))
33
34 err = Respond(resp,
35 ByDiscardingBody(),
36 ByClosing())
37```
38
39Each phase relies on decorators to modify and / or manage processing. Decorators may first modify
40and then pass the data along, pass the data first and then modify the result, or wrap themselves
41around passing the data (such as a logger might do). Decorators run in the order provided. For
42example, the following:
43
44```go
45 req, err := Prepare(&http.Request{},
46 WithBaseURL("https://microsoft.com/"),
47 WithPath("a"),
48 WithPath("b"),
49 WithPath("c"))
50```
51
52will set the URL to:
53
54```
55 https://microsoft.com/a/b/c
56```
57
58Preparers and Responders may be shared and re-used (assuming the underlying decorators support
59sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders
60shared among multiple go-routines, and a single Sender shared among multiple sending go-routines,
61all bound together by means of input / output channels.
62
63Decorators hold their passed state within a closure (such as the path components in the example
64above). Be careful to share Preparers and Responders only in a context where such held state
65applies. For example, it may not make sense to share a Preparer that applies a query string from a
66fixed set of values. Similarly, sharing a Responder that reads the response body into a passed
67struct (e.g., `ByUnmarshallingJson`) is likely incorrect.
68
69Errors raised by autorest objects and methods will conform to the `autorest.Error` interface.
70
71See the included examples for more detail. For details on the suggested use of this package by
72generated clients, see the Client described below.
73
74## Helpers
75
76### Handling Swagger Dates
77
78The Swagger specification (https://swagger.io) that drives AutoRest
79(https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The
80github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct
81parsing and formatting.
82
83### Handling Empty Values
84
85In JSON, missing values have different semantics than empty values. This is especially true for
86services using the HTTP PATCH verb. The JSON submitted with a PATCH request generally contains
87only those values to modify. Missing values are to be left unchanged. Developers, then, require a
88means to both specify an empty value and to leave the value out of the submitted JSON.
89
90The Go JSON package (`encoding/json`) supports the `omitempty` tag. When specified, it omits
91empty values from the rendered JSON. Since Go defines default values for all base types (such as ""
92for string and 0 for int) and provides no means to mark a value as actually empty, the JSON package
93treats default values as meaning empty, omitting them from the rendered JSON. This means that, using
94the Go base types encoded through the default JSON package, it is not possible to create JSON to
95clear a value at the server.
96
97The workaround within the Go community is to use pointers to base types in lieu of base types within
98structures that map to JSON. For example, instead of a value of type `string`, the workaround uses
99`*string`. While this enables distinguishing empty values from those to be unchanged, creating
100pointers to a base type (notably constant, in-line values) requires additional variables. This, for
101example,
102
103```go
104 s := struct {
105 S *string
106 }{ S: &"foo" }
107```
108fails, while, this
109
110```go
111 v := "foo"
112 s := struct {
113 S *string
114 }{ S: &v }
115```
116succeeds.
117
118To ease using pointers, the subpackage `to` contains helpers that convert to and from pointers for
119Go base types which have Swagger analogs. It also provides a helper that converts between
120`map[string]string` and `map[string]*string`, enabling the JSON to specify that the value
121associated with a key should be cleared. With the helpers, the previous example becomes
122
123```go
124 s := struct {
125 S *string
126 }{ S: to.StringPtr("foo") }
127```
128
129## Install
130
131```bash
132go get github.com/Azure/go-autorest/autorest
133go get github.com/Azure/go-autorest/autorest/azure
134go get github.com/Azure/go-autorest/autorest/date
135go get github.com/Azure/go-autorest/autorest/to
136```
137
138### Using with Go Modules
139In [v12.0.1](https://github.com/Azure/go-autorest/pull/386), this repository introduced the following modules.
140
141- autorest/adal
142- autorest/azure/auth
143- autorest/azure/cli
144- autorest/date
145- autorest/mocks
146- autorest/to
147- autorest/validation
148- autorest
149- logger
150- tracing
151
152Tagging cumulative SDK releases as a whole (e.g. `v12.3.0`) is still enabled to support consumers of this repo that have not yet migrated to modules.
153
154## License
155
156See LICENSE file.
157
158-----
159
160This project has adopted the [Microsoft Open Source Code of
161Conduct](https://opensource.microsoft.com/codeofconduct/). For more information
162see the [Code of Conduct
163FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
164[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional
165questions or comments.
166
){kind=link}