{"id":31646415,"url":"https://github.com/fnt-eve/goesi-openapi","last_synced_at":"2026-03-13T08:07:56.304Z","repository":{"id":317287426,"uuid":"1066746209","full_name":"fnt-eve/goesi-openapi","owner":"fnt-eve","description":"Go client library for EVE Online's ESI API with OAuth2 authentication, PKCE support, and automatic spec updates","archived":false,"fork":false,"pushed_at":"2026-03-04T06:35:26.000Z","size":1277,"stargazers_count":7,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-04T13:08:07.666Z","etag":null,"topics":["api-client","esi","eve-api","eve-online","gaming","golang","jwt","oauth2","openapi"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/fnt-eve/goesi-openapi","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fnt-eve.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T22:47:09.000Z","updated_at":"2026-03-04T06:35:28.000Z","dependencies_parsed_at":"2025-09-30T02:26:59.206Z","dependency_job_id":"0a037e78-d003-487d-9845-29a63feb5210","html_url":"https://github.com/fnt-eve/goesi-openapi","commit_stats":null,"previous_names":["fnt-eve/goesi-openapi"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/fnt-eve/goesi-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnt-eve%2Fgoesi-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnt-eve%2Fgoesi-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnt-eve%2Fgoesi-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnt-eve%2Fgoesi-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnt-eve","download_url":"https://codeload.github.com/fnt-eve/goesi-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnt-eve%2Fgoesi-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30462087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-client","esi","eve-api","eve-online","gaming","golang","jwt","oauth2","openapi"],"created_at":"2025-10-07T05:49:38.918Z","updated_at":"2026-03-13T08:07:56.281Z","avatar_url":"https://github.com/fnt-eve.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GoESI OpenAPI Client\n\n[![Go Version](https://img.shields.io/badge/go-%3E%3D1.24-blue.svg)](https://golang.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA Go client library for the [EVE Online ESI API](https://esi.evetech.net/), generated from the official OpenAPI specification.\n\n## About\n\nThis library is a spiritual successor to the original [goesi](https://github.com/antihax/goesi) package, updated to support CCP's OpenAPI 3.x+ specification. When CCP migrated ESI to OpenAPI 3.0+, a new code generation approach was needed to maintain compatibility with the updated specification format.\n\n## Installation\n\n```bash\ngo get github.com/fnt-eve/goesi-openapi\n```\n\n## Quick Start\n\n### Public API (No Authentication)\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n\n    \"github.com/fnt-eve/goesi-openapi\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    \n    // Create client for public endpoints\n    client := goesi.NewPublicESIClient(\"MyApp/1.0 (contact@example.com)\")\n    \n    // Get system information\n    system, _, err := client.UniverseAPI.GetUniverseSystemsSystemId(ctx, 30000142).Execute()\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    log.Printf(\"System: %s\", system.GetName())\n}\n```\n\n### Authenticated API\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \"os\"\n\n    \"github.com/fnt-eve/goesi-openapi\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    \n    // Set up OAuth2\n    clientID := os.Getenv(\"ESI_CLIENT_ID\")\n    redirectURL := \"http://localhost:8080/callback\"\n    \n    // Create JWT key function for token validation\n    keyFunc, err := goesi.ESIDefaultKeyfunc(ctx)\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // Create OAuth2 config\n    config, err := goesi.NewConfig(clientID, redirectURL, \u0026keyFunc)\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // Get authorization URL with requested scopes\n    state := \"random-state-string\"\n    scopes := []string{goesi.ScopeLocationReadLocationV1}\n    authURL := config.AuthURL(state, scopes)\n    log.Printf(\"Visit: %s\", authURL)\n    \n    // Exchange code for token (after user authorization)\n    // var code string // Get this from the callback\n    // token, claims, err := config.Exchange(ctx, code, state, state)\n    // if err != nil {\n    //     log.Fatal(err)\n    // }\n    \n    // Create authenticated client\n    // client := goesi.NewAuthenticatedESIClient(ctx, config, token, \"MyApp/1.0 (contact@example.com)\")\n}\n```\n\n## OAuth2 Authentication\n\nESI uses OAuth2 with PKCE. The authentication flow:\n\n1. **Create config** with client ID and redirect URL\n2. **Generate auth URL** with requested scopes and redirect user to authorize\n3. **Exchange code** for access token\n4. **Use token** to make authenticated API calls\n5. **Refresh token** when it expires\n\n### Available Scopes\n\nThe library includes constants for all ESI scopes:\n\n```go\nscopes := []string{\n    goesi.ScopeLocationReadLocationV1,\n    goesi.ScopeAssetsReadAssetsV1, \n    goesi.ScopeSkillsReadSkillsV1,\n    goesi.ScopeCorporationsReadBlueprintsV1,\n    // ... many more\n}\n```\n\n### JWT Token Information\n\nAccess tokens are JWTs containing character information. The `Exchange` method returns both the token and parsed claims:\n\n```go\n// Exchange authorization code for token and claims\ntoken, claims, err := config.Exchange(ctx, code, state, state)\nif err != nil {\n    log.Fatal(err)\n}\n\n// Extract character information from claims\ncharacterID, err := claims.CharacterID()    // int32\ncharacterName := claims.Name                 // string\nscopes := claims.Scopes                      // []string\n```\n\n## API Usage\n\nThe generated client provides access to all ESI endpoints through API groups:\n\n```go\nclient := goesi.NewPublicESIClient(\"MyApp/1.0 (contact@example.com)\")\n\n// Character information\nclient.CharacterAPI.GetCharactersCharacterId(ctx, characterID)\n\n// Market data  \nclient.MarketAPI.GetMarketsRegionIdOrders(ctx, regionID)\n\n// Universe data\nclient.UniverseAPI.GetUniverseSystemsSystemId(ctx, systemID)\n\n// Corporation data\nclient.CorporationAPI.GetCorporationsCorporationId(ctx, corporationID)\n\n// Alliance data\nclient.AllianceAPI.GetAlliancesAllianceId(ctx, allianceID)\n```\n\n## Error Handling\n\n```go\ndata, response, err := client.CharacterAPI.GetCharactersCharacterId(ctx, characterID).Execute()\nif err != nil {\n    if apiErr, ok := err.(*esi.GenericOpenAPIError); ok {\n        log.Printf(\"API Error: %s\", apiErr.Error())\n        log.Printf(\"Response: %s\", apiErr.Body())\n    } else {\n        log.Printf(\"Other error: %v\", err)\n    }\n    return\n}\n```\n\n## Token Management\n\n```go\n// Check if token needs refresh\nif goesi.IsExpired(token) {\n    newToken, newClaims, err := config.RefreshToken(ctx, token)\n    if err != nil {\n        log.Fatal(\"Token refresh failed:\", err)\n    }\n    token = newToken\n    claims = newClaims\n}\n\n// Store/load tokens (stores only the oauth2.Token, not claims)\ntokenJSON, _ := goesi.TokenToJSON(token)\n// Store tokenJSON in database/file\n\n// Later: restore token and parse claims\nstoredToken, _ := goesi.TokenFromJSON(tokenJSON)\nclaims, err := config.ParseClaims(storedToken)\nif err != nil {\n    log.Fatal(\"Failed to parse claims:\", err)\n}\n```\n\n## Rate Limits\n\nESI rate limits:\n- **20 requests/second** for authenticated requests  \n- **10 requests/second** for public requests\n\nThe client automatically includes required headers like `X-Compatibility-Date`.\n\n## Examples\n\nSee [`examples/`](examples/) directory:\n- [`basic-oauth2/`](examples/basic-oauth2/main.go) - Complete OAuth2 flow with authenticated client\n- [`context-auth/`](examples/context-auth/main.go) - Context-based authentication pattern\n- [`token-persistence/`](examples/token-persistence/main.go) - Token serialization and TokenSource usage\n\n## Development\n\n### Code Generation\n\nThe client is generated from the ESI OpenAPI specification:\n\n```bash\nmake generate\n```\n\nThis downloads the latest ESI spec, generates the client code, and runs post-processing scripts.\n\n### Building\n\n```bash\ngo build ./...\ngo test ./...\ngo run examples/oauth2_example.go\n```\n\n## Library Configuration\n\n### User Agent \n\nESI requires all requests to include a User-Agent header with contact information:\n\n```go\nuserAgent := \"MyEVEApp/1.0 (contact@example.com)\"\nclient := goesi.NewPublicESIClient(userAgent)\n```\n\nFormat: `AppName/Version (contact-email)`\n\n## Running Examples\n\nThe examples require an ESI application registration:\n\n### 1. Register Your Application\n\nVisit [EVE Developers](https://developers.eveonline.com/) to create an application and get a Client ID.\n\n### 2. Set Environment Variables\n\n```bash\nexport ESI_CLIENT_ID=\"your-client-id-from-developers-portal\"\n```\n\n### 3. Run Examples\n\n```bash\ngo run examples/basic-oauth2/main.go\ngo run examples/context-auth/main.go\n```\n\n## Dependencies\n\n- `golang.org/x/oauth2` - OAuth2 client\n- `github.com/golang-jwt/jwt/v5` - JWT token parsing\n- `github.com/MicahParks/keyfunc/v3` - JWT key validation\n\n## Requirements\n\n- Go 1.24+\n- Valid ESI application registration\n\n## Resources\n\n- [ESI Documentation](https://esi.evetech.net/ui/)\n- [ESI OpenAPI Spec](https://esi.evetech.net/meta/openapi-3.0.json)\n- [Developer Resources](https://developers.eveonline.com/)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Disclaimer\n\nNot affiliated with CCP Games. EVE Online is a trademark of CCP hf.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnt-eve%2Fgoesi-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnt-eve%2Fgoesi-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnt-eve%2Fgoesi-openapi/lists"}