Build a Praxa backend with Go

​

Prerequisites

• a trusted server runtime and application authentication boundary;
• a disposable personal workspace Praxa key with only the tutorial’s required scopes;
• synthetic input plus a persisted application request ID for replay tests;
• a fake upstream for unit tests and a non-production environment for canaries;
• an acceptance assertion that proves the Go handler reuses its client, respects context cancellation, and reconciles one durable run.

​

1. Implement the client

package praxa

import (
	"bytes"
	"context"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

type Client struct {
	HTTPClient *http.Client
	APIKey     string
	Origin     string
}

type Run struct {
	RunID  string `json:"run_id"`
	Status string `json:"status"`
}

func New(apiKey string) *Client {
	return &Client{
		HTTPClient: &http.Client{Timeout: 30 * time.Second},
		APIKey:     apiKey,
		Origin:     "https://api.praxa.io",
	}
}

func (c *Client) SubmitTask(
	ctx context.Context,
	userID string,
	logicalRequestID string,
	input string,
) (Run, error) {
	if len(input) < 1 || len(input) > 16_000 {
		return Run{}, fmt.Errorf("invalid task input")
	}

	digest := sha256.Sum256([]byte(userID + "\x00" + logicalRequestID))
	key := "go:" + hex.EncodeToString(digest[:])
	body := map[string]any{
		"apiVersion":    "v1",
		"requestId":     key,
		"mode":          "task",
		"task":          map[string]string{"input": input},
		"idempotencyKey": key,
	}
	encoded, err := json.Marshal(body)
	if err != nil {
		return Run{}, err
	}

	request, err := http.NewRequestWithContext(
		ctx,
		http.MethodPost,
		c.Origin+"/v1/execute",
		bytes.NewReader(encoded),
	)
	if err != nil {
		return Run{}, err
	}
	request.Header.Set("Authorization", "Bearer "+c.APIKey)
	request.Header.Set("Content-Type", "application/json")
	request.Header.Set("Idempotency-Key", key)

	response, err := c.HTTPClient.Do(request)
	if err != nil {
		return Run{}, err
	}
	defer response.Body.Close()
	if response.StatusCode < 200 || response.StatusCode >= 300 {
		return Run{}, fmt.Errorf("Praxa returned HTTP %d", response.StatusCode)
	}

	var run Run
	if err := json.NewDecoder(response.Body).Decode(&run); err != nil {
		return Run{}, err
	}
	return run, nil
}

​

2. Add the application handler

​

3. Test with httptest

• the handler receives exactly one POST;
• authorization never appears in application output;
• repeated user/request pairs produce the same key;
• changed users produce different keys;
• invalid input makes no request;
• non-2xx responses remain errors;
• context cancellation stops the local HTTP request.

go test ./...
go vet ./...

​

4. Verify end to end

​

Troubleshooting

​

Best practices

• Reuse http.Client and its transport.
• Pass request contexts through every layer.
• Use typed request/response structures in production.
• Bound body size before decoding.
• Rate-limit per authenticated principal.
• Keep idempotency records until the operation is reconciled.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?