iterate on APIClient

atproto/client/api_client.go

···
 	"encoding/json"
 	"fmt"
 	"net/http"
+	"net/url"
 
 	"github.com/bluesky-social/indigo/atproto/syntax"
 )
 
 type APIClient struct {
-	HTTPClient     *http.Client
+	// inner HTTP client
+	Client         *http.Client
+
+	// host URL prefix: scheme, hostname, and port. This field is required.
 	Host           string
+
+	// optional auth client "middleware"
 	Auth           AuthMethod
-	DefaultHeaders map[string]string
+
+	// optional HTTP headers which will be included in all requests. Only a single value per key is included; request-level headers will override any client-level defaults.
+	DefaultHeaders http.Header
 }
 
 // High-level helper for simple JSON "Query" API calls.
 //
 // Does not work with all API endpoints. For more control, use the Do() method with APIRequest.
-func (c *APIClient) Get(ctx context.Context, endpoint syntax.NSID, params map[string]string, out any) error {
-	hdr := map[string]string{
-		"Accept": "application/json",
+func (c *APIClient) Get(ctx context.Context, endpoint syntax.NSID, params url.Values, out any) error {
+	hdr := map[string][]string{
+		"Accept": []string{"application/json"},
 	}
 	req := APIRequest{
-		HTTPVerb:    "GET",
+		Method:      http.MethodGet,
 		Endpoint:    endpoint,
 		Body:        nil,
 		QueryParams: params,
···
 	if err != nil {
 		return err
 	}
-
 	defer resp.Body.Close()
-	// TODO: duplicate error handling with Post()?
+
 	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
 		var eb ErrorBody
 		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
···
 	return nil
 }
 
-// High-level helper for simple JSON-to-JSON "Procedure" API calls.
+// High-level helper for simple JSON-to-JSON "Procedure" API calls, with no query params.
 //
-// Does not work with all API endpoints. For more control, use the Do() method with APIRequest.
+// Does not work with all possible atproto API endpoints. For more control, use the Do() method with APIRequest.
 func (c *APIClient) Post(ctx context.Context, endpoint syntax.NSID, body any, out any) error {
 	bodyJSON, err := json.Marshal(body)
 	if err != nil {
 		return err
 	}
-	hdr := map[string]string{
-		"Accept":       "application/json",
-		"Content-Type": "application/json",
+	hdr := map[string][]string{
+		"Accept":       []string{"application/json"},
+		"Content-Type": []string{"application/json"},
 	}
 	req := APIRequest{
-		HTTPVerb:    "POST",
+		Method:      http.MethodPost,
 		Endpoint:    endpoint,
 		Body:        bytes.NewReader(bodyJSON),
 		QueryParams: nil,
···
 	if err != nil {
 		return err
 	}
-
 	defer resp.Body.Close()
-	// TODO: duplicate error handling with Get()?
+
 	if !(resp.StatusCode >= 200 && resp.StatusCode < 300) {
 		var eb ErrorBody
 		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
···
 }
 
 // Full-power method for atproto API requests.
+//
+// NOTE: this does not currently parse error response JSON body, thought it might in the future.
 func (c *APIClient) Do(ctx context.Context, req APIRequest) (*http.Response, error) {
 	httpReq, err := req.HTTPRequest(ctx, c.Host, c.DefaultHeaders)
 	if err != nil {
 		return nil, err
 	}
 
-	// TODO: thread-safe?
-	if c.HTTPClient == nil {
-		c.HTTPClient = http.DefaultClient
+	// NOTE: this updates the client object itself
+	if c.Client == nil {
+		c.Client = http.DefaultClient
 	}
 
 	var resp *http.Response
 	if c.Auth != nil {
-		resp, err = c.Auth.DoWithAuth(c.HTTPClient, httpReq)
+		resp, err = c.Auth.DoWithAuth(c.Client, httpReq)
 	} else {
-		resp, err = c.HTTPClient.Do(httpReq)
+		resp, err = c.Client.Do(httpReq)
 	}
 	if err != nil {
 		return nil, err
 	}
-	// TODO: handle some common response errors: rate-limits, 5xx, auth required, etc
 	return resp, nil
 }
+
+func NewPublicClient(host string) *APIClient {
+	return &APIClient{
+		Client: http.DefaultClient,
+		Host: host,
+		DefaultHeaders: map[string][]string{
+			"User-Agent": []string{"indigo-sdk"},
+		},
+	}
+}

atproto/client/api_request.go

···
 import (
 	"context"
 	"io"
+	"fmt"
 	"net/http"
 	"net/url"
 
 	"github.com/bluesky-social/indigo/atproto/syntax"
 )
 
+var (
+	// atproto API "Query" Lexicon method, which is HTTP GET. Not to be confused with proposed "HTTP QUERY" method.
+	MethodQuery = http.MethodGet
+
+	// atproto API "Procedure" Lexicon method, which is HTTP POST.
+	MethodProcedure = http.MethodPost
+)
+
 type APIRequest struct {
-	HTTPVerb    string // TODO: type?
+	// HTTP method, eg "GET" (required)
+	Method      string
+
+	// atproto API endpoint, as NSID (required)
 	Endpoint    syntax.NSID
+
+	// optional request body. if this is provided, then 'Content-Type' header should be specified
 	Body        io.Reader
-	QueryParams map[string]string // TODO: better type for this?
-	Headers     map[string]string
+
+	// optional query parameters. These will be encoded as provided.
+	QueryParams url.Values
+
+	// optional HTTP headers. Only the first value will be included for each header key ("Set" behavior).
+	Headers     http.Header
 }
 
-func (r *APIRequest) HTTPRequest(ctx context.Context, host string, headers map[string]string) (*http.Request, error) {
+// Turns the API request in to an `http.Request`.
+//
+// `host` parameter should be a URL prefix: schema, hostname, port.
+// `headers` parameters are treated as client-level defaults. Only a single value is allowed per key ("Set" behavior), and will be clobbered by any request-level header values.
+func (r *APIRequest) HTTPRequest(ctx context.Context, host string, headers http.Header) (*http.Request, error) {
 	u, err := url.Parse(host)
 	if err != nil {
 		return nil, err
 	}
+	if u.Host == "" {
+		return nil, fmt.Errorf("empty hostname in host URL")
+	}
+	if u.Scheme == "" {
+		return nil, fmt.Errorf("empty scheme in host URL")
+	}
+	if r.Endpoint == "" {
+		return nil, fmt.Errorf("empty request endpoint")
+	}
 	u.Path = "/xrpc/" + r.Endpoint.String()
+	u.RawQuery = nil
 	if r.QueryParams != nil {
-		q := u.Query()
-		for k, v := range r.QueryParams {
-			q.Add(k, v)
-		}
-		u.RawQuery = q.Encode()
+		u.RawQuery = r.QueryParams.Encode()
 	}
-	httpReq, err := http.NewRequestWithContext(ctx, r.HTTPVerb, u.String(), r.Body)
+	httpReq, err := http.NewRequestWithContext(ctx, r.Method, u.String(), r.Body)
 	if err != nil {
 		return nil, err
 	}
 
 	// first set default headers...
 	if headers != nil {
-		for k, v := range headers {
-			httpReq.Header.Set(k, v)
+		for k := range headers {
+			httpReq.Header.Set(k, headers.Get(k))
 		}
 	}
 
 	// ... then request-specific take priority (overwrite)
 	if r.Headers != nil {
-		for k, v := range r.Headers {
-			httpReq.Header.Set(k, v)
+		for k := range r.Headers {
+			httpReq.Header.Set(k, headers.Get(k))
 		}
 	}