Requests and responses

The shared Request, the per-verb request types, and the buffered and streamed Response.

Every verb takes a request that carries or embeds the shared Request, and the buffered verbs return a *Response.

Request

type Request struct {
	ID		string
	SessionID	string
	Path		string
	Query		url.Values
	Headers		map[string]string
	// Stream, when true, skips buffering the response body into Response.Body and
	// hands the live stream back as Response.Reader instead, so large downloads never
	// round-trip through memory. The caller must Close the Response. Default false
	// keeps the buffered Body behavior every other caller relies on.
	Stream	bool
}

The shared shape of every request. Path is joined to the client's base URL. Query is encoded onto the path. Headers are merged over the client-wide headers and win on a name clash. ID and SessionID are emitted as X-Request-ID and X-Session-ID when set. Stream switches the response body from buffered to live. See Request options.

Per-verb requests

GetRequest wraps a Request with no body.

type GetRequest struct {
	Request
}

PostRequest adds a Body. PutRequest and PatchRequest share its shape.

type PostRequest struct {
	Request

	Body	[]byte
}

type PutRequest PostRequest

type PatchRequest PostRequest

Delete takes a bare Request and sends no body.

Response

type Response struct {
	StatusCode	int
	// Body holds the fully-read response for a buffered request (Request.Stream
	// false, the default). It is nil for a streamed request, where Reader carries
	// the live body instead.
	Body	[]byte
	// Reader is the live, unread response body of a streamed request (Request.Stream
	// true). The caller owns it and must Close it (Response itself is an io.ReadCloser
	// over it, so io.Copy(dst, resp) then resp.Close() works). It is nil for a
	// buffered request.
	Reader	io.ReadCloser
	Headers	http.Header
	Error	error
}

The outcome of a request. For a buffered request Body holds the fully-read response and Reader is nil. For a streamed request (Request.Stream true) Reader carries the live body and Body is nil. Response is an io.ReadCloser over Reader, so a streamed response passes straight to io.Copy and must be closed. Close is a no-op on a buffered response.

StreamResponse

type StreamResponse struct {
	StatusCode	int
	Body		[]byte
	Headers		http.Header
	Error		error
	Type		StreamResponseType
}

One decoded Server-Sent Events frame from a streaming call. Type classifies the line and Body holds the decoded value with the wire prefix stripped. See Streaming.

type StreamResponseType string

The frame type is one of StreamResponseTypeData, StreamResponseTypeEvent, StreamResponseTypeID, StreamResponseTypeRetry, StreamResponseTypeComment, or StreamResponseTypeEOF.

Edit or read the source on GitHub