tplinkomadasdkforgo

README

tplink-omada-sdk-for-go

Go SDK for the TP-Link Omada Controller Open API, generated with Kiota from omada-open-api-sec.json. It covers the full API surface (1,500+ endpoints / 2,700+ schemas) as strongly-typed, fluent request builders under openapi/ and models/.

Install

go get github.com/NerdIT-Tech/tplink-omada-sdk-for-go

Quickstart

client, err := sdk.NewWithClientCredentials(
    "https://192.168.1.1:8043", // controller base URL
    clientID, clientSecret,
    omadacID, // from GET {baseURL}/api/info, unauthenticated
    sdk.NewInsecureHTTPClient(), // self-signed cert on the local controller
)

page, pageSize := int32(1), int32(10)
resp, err := client.Openapi().V1().ByOmadacId(omadacID).Sites().Get(ctx, &openapi.V1ItemSitesRequestBuilderGetRequestConfiguration{
    QueryParameters: &openapi.V1ItemSitesRequestBuilderGetQueryParameters{
        Page:     &page,
        PageSize: &pageSize,
    },
})

Documentation

Full docs site: https://NerdIT-Tech.github.io/tplink-omada-sdk-for-go/ (built from the markdown below via Docusaurus; see docs/contributor/documentation.md for how it's set up).

User Guide — for applications built against the SDK:

• Introduction — install and a quickstart
• Authentication & TLS — client construction options and an important gotcha with the controller's Authorization header scheme
• Using the SDK — the fluent request builder pattern, query parameters, reading responses, error handling, and a worked example

Contributor Guide — for working on the SDK itself:

• Architecture — module layout and the generated-vs-hand-written boundary
• Regenerating the SDK — the Kiota command and a post-generation fix to re-apply
• Testing against a live controller — the bdd/ Godog suite
• CI & Release — what each GitHub Actions workflow gates, and how release-please drives versioning
• Documentation — how this doc split and the website/ Docusaurus site work
• QA Report — bugs found and fixed during BDD testing

Documentation

Overview

Package tplinkomadasdkforgo is a Go SDK for the TP-Link Omada Controller Open API. NewWithClientCredentials and NewWithAccessToken construct an *OmadaApiClient; every generated endpoint is then reachable through its fluent Openapi() builder chain.

Index

• Constants
• func NewInsecureHTTPClient() *http.Client
• type OmadaApiClient
  • func NewOmadaApiClient(...) *OmadaApiClient
  • func NewWithAccessToken(baseURL, accessToken string, httpClient *http.Client) (*OmadaApiClient, error)
  • func NewWithClientCredentials(baseURL, clientID, clientSecret, omadacID string, httpClient *http.Client) (*OmadaApiClient, error)
  • func (m *OmadaApiClient) Openapi() ...

Constants

const Version = "0.2.0"

Version is the current version of the SDK x-release-please-start-version

Functions

func NewInsecureHTTPClient

func NewInsecureHTTPClient() *http.Client

NewInsecureHTTPClient returns an *http.Client that skips TLS certificate verification. Omada controllers are typically self-hosted on a local network with a self-signed certificate, so this is a convenience for that common case; prefer a properly configured *http.Client (e.g. with the controller's CA trusted) whenever possible.

Types

type OmadaApiClient

type OmadaApiClient struct {
	i2ae4187f7daee263371cb1c977df639813ab50ffa529013b7437480d1ec0158f.BaseRequestBuilder
}

OmadaApiClient the main entry point of the SDK, exposes the configuration and the fluent API.

func NewOmadaApiClient

func NewOmadaApiClient(requestAdapter i2ae4187f7daee263371cb1c977df639813ab50ffa529013b7437480d1ec0158f.RequestAdapter) *OmadaApiClient

NewOmadaApiClient instantiates a new OmadaApiClient and sets the default values.

func NewWithAccessToken

func NewWithAccessToken(baseURL, accessToken string, httpClient *http.Client) (*OmadaApiClient, error)

NewWithAccessToken creates an OmadaApiClient that authenticates every request with a caller-supplied bearer access token, e.g. one an application obtained and manages itself. baseURL is the controller's Open API base URL (e.g. "https://192.168.1.1:8043"). If httpClient is nil, a default client with TLS verification enabled is used; pass NewInsecureHTTPClient() for controllers with self-signed certificates.

func NewWithClientCredentials

func NewWithClientCredentials(baseURL, clientID, clientSecret, omadacID string, httpClient *http.Client) (*OmadaApiClient, error)

NewWithClientCredentials creates an OmadaApiClient that authenticates using an Omada Open API client ID and client secret (registered under Settings > Platform Integration on the controller). The access token is fetched on first use and transparently refreshed before it expires. omadacID scopes the credentials to a specific Omada Cloud Controller ID; pass "" if not applicable. If httpClient is nil, a default client with TLS verification enabled is used; pass NewInsecureHTTPClient() for controllers with self-signed certificates.

func (*OmadaApiClient) Openapi

func (m *OmadaApiClient) Openapi() *i9ce3403bdbc5744950a37f250f576a6f889cfd2325b6933113727352a0aa74e8.OpenapiRequestBuilder

Openapi the openapi property returns a *OpenapiRequestBuilder when successful