Skip to content

README.md

Latest commit

 

History

History
147 lines (112 loc) · 5.07 KB

README.md

File metadata and controls

147 lines (112 loc) · 5.07 KB
Raw

Go client

Go client for the Photon API, generated from the public OpenAPI contract. Requires Go 1.25+ and has no dependencies outside the standard library.

Installation

go get github.com/photon-hq/api/packages/go

Quickstart

package main

import (
    "context"
    "errors"
    "log"
    "os"

    photonapi "github.com/photon-hq/api/packages/go"
)

func main() {
    client := photonapi.NewClient(photonapi.WithAPIKey(os.Getenv("PHOTON_API_TOKEN")))

    orgs, err := client.Organizations.ListOrganizations(context.Background())
    var apiErr *photonapi.APIError
    if errors.As(err, &apiErr) {
        log.Fatalln(apiErr.Code(), apiErr.RequestID)
    }
    if err != nil {
        log.Fatalln(err)
    }
    log.Println(orgs)
}

Set PHOTON_API_TOKEN to an Account Service Key (pho_ask_...) or another supported credential. See the Photon dashboard and documentation to create credentials.

Authentication

  • WithAPIKey sends a static credential (project API key, account service key, or a service identity API key) as Authorization: Bearer.
  • WithTokenSource supplies a token that refreshes, such as an OAuth or M2M access token; the source runs before requests that need it.

The SDK does not run OAuth flows. Obtain OAuth access tokens and manage refresh in your application's own authentication flow, then supply the current token.

Using the client

  • Services mirror the API namespaces: client.Organizations, client.Projects.Platforms, and so on. A method takes a context.Context, a *<Operation>Params struct (path, query and header parameters and Body) when the operation has any, and optional RequestOptions.
  • Response metadata: pass photonapi.WithResponseInfo(&info) to receive the status, headers and request ID. Downloads return a *BinaryResponse whose Body the caller closes.
  • Forward compatibility: enums are plain string types (unknown values pass through), unknown response members are ignored, and unions are Union values that keep the raw JSON; branch on Kind() and decode with As<Member>(). Timestamps are Timestamp (UTC, millisecond precision).

Errors

Methods return *APIError for a documented error status (with the HTTP status, the problem body as Problem, the request ID and a capped raw body), *TransportError for connection failures, and *ResponseDecodeError when a response body does not match its model.

Retries and timeouts

Requests that fail with 408, 429, 502, 503 or 504, or with a transport error, are retried for reads and for writes that carry an Idempotency-Key; the client generates the key when the params field is empty and reuses it across retries. Retry-After is honoured up to WithMaxRetryAfter (60 seconds by default). WithMaxRetries and WithRetryDelay adjust the policy, and WithHTTPClient supplies your own *http.Client with its own timeout.

Base URL

The client uses https://api.photon.codes (exported as DefaultBaseURL). For tests and alternative environments, pass WithBaseURL:

client := photonapi.NewClient(
    photonapi.WithBaseURL("http://localhost:8080"),
    photonapi.WithAPIKey(token),
)

API reference

The full method and type reference is on pkg.go.dev. The OpenAPI contract this client is generated from is openapi/openapi.json in photon-hq/api, with a Postman collection generated from it. The same repository contains the TypeScript, Python and Rust clients.

Versioning

The TypeScript, Python, Rust and Go clients share one version and are released together; the Go module is versioned by the packages/go/vX.Y.Z tag. Releases follow semantic versioning, starting at 0.1.0. Before 1.0, breaking changes increase the minor version. Changes are listed in CHANGELOG.md.

Building from source

Generation requires Node.js 26, Python 3.11+ and Go. From the repository root:

npm ci
npm run regenerate:go
npm run test:go

*_generated.go files are generated by tools/go-codegen; client.go, errors.go and types.go are hand-written. CI regenerates the client from the committed contract and fails if the output differs from the committed files.

Support and security

Report bugs and requests through GitHub issues. Do not include credentials or private data. Report vulnerabilities privately as described in SECURITY.md.

This repository is generated, so external pull requests are not accepted. See CONTRIBUTING.md.

License

MIT. See LICENSE and NOTICE.