{"id":22089833,"url":"https://github.com/speakeasy-api/speakeasy-go-sdk","last_synced_at":"2025-07-24T19:31:33.645Z","repository":{"id":50519526,"uuid":"502708643","full_name":"speakeasy-api/speakeasy-go-sdk","owner":"speakeasy-api","description":"Speakeasy Serverside SDK for Go REST APIs","archived":false,"fork":false,"pushed_at":"2024-02-26T21:58:02.000Z","size":330,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-11-30T19:44:55.075Z","etag":null,"topics":["api-platform","apiops","go-rest-api","go-restful","golang","rest","sdk","sdk-go"],"latest_commit_sha":null,"homepage":"https://www.speakeasyapi.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speakeasy-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-12T19:26:42.000Z","updated_at":"2024-03-22T00:58:30.000Z","dependencies_parsed_at":"2024-02-26T23:04:36.991Z","dependency_job_id":null,"html_url":"https://github.com/speakeasy-api/speakeasy-go-sdk","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fspeakeasy-go-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fspeakeasy-go-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fspeakeasy-go-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speakeasy-api%2Fspeakeasy-go-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speakeasy-api","download_url":"https://codeload.github.com/speakeasy-api/speakeasy-go-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227470069,"owners_count":17778930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-platform","apiops","go-rest-api","go-restful","golang","rest","sdk","sdk-go"],"created_at":"2024-12-01T02:14:25.211Z","updated_at":"2024-12-01T02:14:25.888Z","avatar_url":"https://github.com/speakeasy-api.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# speakeasy-go-sdk\n\n![180100416-b66263e6-1607-4465-b45d-0e298a67c397](https://user-images.githubusercontent.com/68016351/181640742-31ab234a-3b39-432e-b899-21037596b360.png)\n\nSpeakeasy is your API Platform team as a service. Use our drop in SDK to manage all your API Operations including embeds for request logs and usage dashboards, schema generation from traffic, and understanding API drift.\n\nThe Speakeasy Go SDK for evaluating API requests/responses. Compatible with any API framework implemented on top of Go's native http library.\n\n## Requirements\n\nSupported routers:\n\n* gorilla/mux\n* go-chi/chi\n* http.DefaultServerMux\n* Routers based on the net/http ServeMux interface such as DataDog's httptrace - https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1@v1.45.1/contrib/net/http\n\nWe also support custom HTTP frameworks:\n\n* gin-gonic/gin\n* labstack/echo\n\n## Usage\n\n\u003e Speakeasy uses [Go Modules](https://github.com/golang/go/wiki/Modules) to manage dependencies.\n\n```shell\ngo get github.com/speakeasy-api/speakeasy-go-sdk\n```\n\n### Minimum configuration\n\n[Sign up for free on our platform](https://www.speakeasyapi.dev/). After you've created a workspace and generated an API key enable Speakeasy in your API as follows:\n\nConfigure Speakeasy at the start of your `main()` function:\n\n```go\nimport \"github.com/speakeasy-api/speakeasy-go-sdk\"\n\nfunc main() {\n\t// Configure the Global SDK\n\tspeakeasy.Configure(speakeasy.Config {\n\t\tAPIKey:\t\t\"YOUR API KEY HERE\",\t// retrieve from Speakeasy API dashboard.\n\t\tApiID:\t\t\"YOUR API ID HERE\", \t// enter a name that you'd like to associate captured requests with.\n        // This name will show up in the Speakeasy dashboard. e.g. \"PetStore\" might be a good ApiID for a Pet Store's API.\n        // No spaces allowed.\n\t\tVersionID:\t\"YOUR VERSION ID HERE\",\t// enter a version that you would like to associate captured requests with.\n        // The combination of ApiID (name) and VersionID will uniquely identify your requests in the Speakeasy Dashboard.\n        // e.g. \"v1.0.0\". You can have multiple versions for the same ApiID (if running multiple versions of your API)\n\t})\n\n    // Associate the SDK's middleware with your router\n\tr := mux.NewRouter()\n\tr.Use(speakeasy.Middleware)\n}\n```\n\n**Note:** Additional middlewares are provided for different routers.\n\nBuild and deploy your app and that's it. Your API is being tracked in the Speakeasy workspace you just created\nand will be visible on the dashboard next time you log in. Visit our [docs site](https://docs.speakeasyapi.dev/) to\nlearn more.\n\n#### Mux-based routers\n\nFor middlewares based on the net/http `ServeMux` interface, use `speakeasy.MiddlewareWithMux`.\n\n#### Gin\n\nFor the [gin](https://github.com/gin-gonic/gin) framework, use `speakeasy.GinMiddlware`.\n\n### Advanced configuration\n\nThe Speakeasy SDK provides both a global and per Api configuration option. If you want to use the SDK to track multiple Apis or Versions from the same service you can configure individual instances of the SDK, like so:\n\n```go\nimport \"github.com/speakeasy-api/speakeasy-go-sdk\"\n\nfunc main() {\n\tr := mux.NewRouter()\n\n\t// Configure a new instance of the SDK for the store API\n\tstoreSDKInstance := speakeasy.New(speakeasy.Config {\n\t\tAPIKey:\t\t\"YOUR API KEY HERE\",\t// retrieve from Speakeasy API dashboard.\n\t\tApiID:\t\t\"store_api\", \t   \t\t// this is an ID you provide that you would like to associate captured requests with.\n\t\tVersionID:\t\"1.0.0\",\t\t\t\t// this is a Version you provide that you would like to associate captured requests with.\n\t})\n\n\t// Configure a new instance of the SDK for the product API\n\tproductSDKInstance := speakeasy.New(speakeasy.Config {\n\t\tAPIKey:\t\t\"YOUR API KEY HERE\",\t// retrieve from Speakeasy API dashboard.\n\t\tApiID:\t\t\"product_api\", \t\t\t// this is an ID you provide that you would like to associate captured requests with.\n\t\tVersionID:\t\"1.0.0\",\t\t\t\t// this is a Version you provide that you would like to associate captured requests with.\n\t})\n\n    // The different instances of the SDK (with differnt IDs or even versions assigned) can be used to associate requests with different APIs and Versions.\n\ts := r.PathPrefix(\"/store\").Subrouter()\n\tr.Use(storeSDKInstance.Middleware)\n\n\ts := r.PathPrefix(\"/products\").Subrouter()\n\tr.Use(productSDKInstance.Middleware)\n}\n```\n\nThis allows multiple instances of the SDK to be associated with different routers or routes within your service.\n\n### On-Premise Configuration\n\nThe SDK provides a way to redirect the requests it captures to an on-premise deployment of the Speakeasy Platform. This is done through the use of environment variables listed below. These are to be set in the environment of your services that have integrated the SDK:\n\n* `SPEAKEASY_SERVER_URL` - The url of the on-premise Speakeasy Platform's GRPC Endpoint. By default this is `grpc.prod.speakeasyapi.dev:443`.\n* `SPEAKEASY_SERVER_SECURE` - Whether or not to use TLS for the on-premise Speakeasy Platform. By default this is `true` set to `SPEAKEASY_SERVER_SECURE=\"false\"` if you are using an insecure connection.\n\n## Request Matching\n\nThe Speakeasy SDK out of the box will do its best to match requests to your provided OpenAPI Schema. It does this by extracting the path template used by one of the supported routers or frameworks above for each request captured and attempting to match it to the paths defined in the OpenAPI Schema, for example:\n\n```go\nr := mux.NewRouter()\nr.Use(sdkInstance.Middleware)\nr.HandleFunc(\"/v1/users/{id}\", MyHandler) // The path template \"/v1/users/{id}\" is captured automatically by the SDK\n```\n\nThis isn't always successful or even possible, meaning requests received by Speakeasy will be marked as `unmatched`, and potentially not associated with your Api, Version or ApiEndpoints in the Speakeasy Dashboard.\n\nTo help the SDK in these situations you can provide path hints per request handler that match the paths in your OpenAPI Schema:\n\n```go\nfunc MyHandler(w http.ResponseWriter, r *http.Request) {\n\t// Provide a path hint for the request using the OpenAPI Path Templating format: https://swagger.io/specification/#path-templating-matching\n\tctrl, ok := speakeasy.MiddlewareController(req)\n\tif ok {\n\t    ctrl.PathHint(\"/v1/users/{id}\")\n    }\n\t// the rest of your handlers code\n}\n```\n\nNotes:  \nWildcard path matching in Echo \u0026 Chi will end up with a OpenAPI path paramater called {wildcard} which will only match single level values represented by the wildcard. This is a restriction of the OpenAPI spec ([Detail Here](https://github.com/OAI/OpenAPI-Specification/issues/892#issuecomment-281449239)). For example: \n\n`chi template: /user/{id}/path/* =\u003e openapi template: /user/{id}/path/{wildcard}`\n\nAnd in the above example a path like `/user/1/path/some/sub/path` won't match but `/user/1/path/somesubpathstring` will, as `/` characters are not matched in path paramters by the OpenAPI spec.\n\n## Capturing Customer IDs\n\nTo help associate requests with customers/users of your APIs you can provide a customer ID per request handler:\n\n```go\nfunc MyHandler(w http.ResponseWriter, r *http.Request) {\n\tctrl, ok := speakeasy.MiddlewareController(req)\n    if ok {\n        ctrl.CustomerID(\"a-customers-id\") // This customer ID will be used to associate this instance of a request with your customers/users\n    }\n\t// the rest of your handlers code\n}\n```\n\nNote: This is not required, but is highly recommended. By setting a customer ID you can easily associate requests with your customers/users in the Speakeasy Dashboard, powering filters in the [Request Viewer](https://docs.speakeasyapi.dev/speakeasy-user-guide/request-viewer).\n\n## Masking sensitive data\n\nSpeakeasy can mask sensitive data in the query string parameters, headers, cookies and request/response bodies captured by the SDK. This is useful for maintaining sensitive data isolation, and retaining control over the data that is captured.\n\nUsing the `Advanced Configuration` section above you can completely ignore certain routes by not assigning the middleware to their router, causing the SDK to not capture any requests to that router.\n\nBut if you would like to be more selective you can mask certain sensitive data using our middleware controller allowing you to mask fields as needed in different handlers:\n\n```go\nfunc MyHandler(w http.ResponseWriter, r *http.Request) {\n\tctrl, _ := speakeasy.MiddlewareController(req)\n\tctrl.Masking(speakeasy.WithRequestHeaderMask(\"Authorization\")) // Mask the Authorization header in the request\n\t\n\t// the rest of your handlers code\n}\n```\n\nThe `Masking` function takes a number of different options to mask sensitive data in the request:\n\n* `speakeasy.WithQueryStringMask` - **WithQueryStringMask** will mask the specified query strings with an optional mask string.\n* `speakeasy.WithRequestHeaderMask` - **WithRequestHeaderMask** will mask the specified request headers with an optional mask string.\n* `speakeasy.WithResponseHeaderMask` - **WithResponseHeaderMask** will mask the specified response headers with an optional mask string.\n* `speakeasy.WithRequestCookieMask` - **WithRequestCookieMask** will mask the specified request cookies with an optional mask string.\n* `speakeasy.WithResponseCookieMask` - **WithResponseCookieMask** will mask the specified response cookies with an optional mask string.\n* `speakeasy.WithRequestFieldMaskString` - **WithRequestFieldMaskString** will mask the specified request body fields with an optional mask. Supports string fields only. Matches using regex.\n* `speakeasy.WithRequestFieldMaskNumber` - **WithRequestFieldMaskNumber** will mask the specified request body fields with an optional mask. Supports number fields only. Matches using regex.\n* `speakeasy.WithResponseFieldMaskString` - **WithResponseFieldMaskString** will mask the specified response body fields with an optional mask. Supports string fields only. Matches using regex.\n* `speakeasy.WithResponseFieldMaskNumber` - **WithResponseFieldMaskNumber** will mask the specified response body fields with an optional mask. Supports number fields only. Matches using regex.\n\nMasking can also be done more globally on all routes or a selection of routes by taking advantage of middleware. Here is an example:\n\n```go\nspeakeasy.Configure(speakeasy.Config {\n\tAPIKey:\t\t\"YOUR API KEY HERE\",\t// retrieve from Speakeasy API dashboard.\n\tApiID:\t\t\"YOUR API ID HERE\", \t// this is an ID you provide that you would like to associate captured requests with.\n\tVersionID:\t\"YOUR VERSION ID HERE\",\t// this is a Version you provide that you would like to associate captured requests with.\n})\n\nr := mux.NewRouter()\nr.Use(speakeasy.Middleware)\nr.Use(func (next http.Handler) http.Handler {\n\treturn http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Mask the Authorization header in the request for all requests served by this middleware\n\t\tctrl, _ := speakeasy.MiddlewareController(req)\n\t\tctrl.Masking(speakeasy.WithRequestHeaderMask(\"Authorization\"))\n\t})\n})\n```\n\n## Embedded Request Viewer Access Tokens\n\nThe Speakeasy SDK can generate access tokens for the [Embedded Request Viewer](https://docs.speakeasyapi.dev/speakeasy-user-guide/request-viewer/embedded-request-viewer) that can be used to view requests captured by the SDK.\n\nFor documentation on how to configure filters, find that [HERE](https://docs.speakeasyapi.dev/speakeasy-user-guide/request-viewer/embedded-request-viewer).\n\nBelow are some examples on how to generate access tokens:\n\n```go\nimport \"github.com/speakeasy-api/speakeasy-schemas/grpc/go/registry/embedaccesstoken\"\n\nctx := context.Background()\n\n// If the SDK is configured as a global instance, an access token can be generated using the `GenerateAccessToken` function on the speakeasy package.\naccessToken, err := speakeasy.GetEmbedAccessToken(ctx, \u0026embedaccesstoken.EmbedAccessTokenRequest{\n\tFilters: []*embedaccesstoken.EmbedAccessTokenRequest_Filter{\n\t\t{\n\t\t\tKey:   \"customer_id\",\n\t\t\tOperator: \"=\",\n\t\t\tValue: \"a-customer-id\",\n\t\t},\n\t},\n})\n\n// If you have followed the `Advanced Configuration` section above you can also generate an access token using the `GenerateAccessToken` function on the sdk instance.\naccessToken, err := storeSDKInstance.GetEmbedAccessToken(ctx, \u0026embedaccesstoken.EmbedAccessTokenRequest{\n\tFilters: []*embedaccesstoken.EmbedAccessTokenRequest_Filter{\n\t\t{\n\t\t\tKey:   \"customer_id\",\n\t\t\tOperator: \"=\",\n\t\t\tValue: \"a-customer-id\",\n\t\t},\n\t},\n})\n\n// Or finally if you have a handler that you would like to generate an access token from, you can get the SDK instance for that handler from the middleware controller and use the `GetEmbedAccessToken` function it.\nfunc MyHandler(w http.ResponseWriter, r *http.Request) {\n\tctrl, _ := speakeasy.MiddlewareController(req)\n\taccessToken, err := ctrl.GetSDKInstance().GetEmbedAccessToken(ctx, \u0026embedaccesstoken.EmbedAccessTokenRequest{\n\t\tFilters: []*embedaccesstoken.EmbedAccessTokenRequest_Filter{\n\t\t\t{\n\t\t\t\tKey:   \"customer_id\",\n\t\t\t\tOperator: \"=\",\n\t\t\t\tValue: \"a-customer-id\",\n\t\t\t},\n\t\t},\n\t})\n\t\n\t// the rest of your handlers code\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fspeakeasy-go-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeakeasy-api%2Fspeakeasy-go-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeakeasy-api%2Fspeakeasy-go-sdk/lists"}