{"id":15137810,"url":"https://github.com/brittonhayes/aos","last_synced_at":"2025-10-23T13:30:49.640Z","repository":{"id":180583254,"uuid":"664956613","full_name":"brittonhayes/aos","owner":"brittonhayes","description":"AoS API (Unofficial) built with Go and Sqlite. Including OpenTelemetry, Grafana, and Jaeger for logs, metrics, and traces.","archived":false,"fork":false,"pushed_at":"2025-01-07T00:48:18.000Z","size":303,"stargazers_count":4,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-06T03:47:44.852Z","etag":null,"topics":["golang","jaeger","observability","open-telemetry","prometheus","tabletop","wargaming","warhammer"],"latest_commit_sha":null,"homepage":"","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/brittonhayes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-07-11T06:03:00.000Z","updated_at":"2025-01-07T00:48:21.000Z","dependencies_parsed_at":"2024-04-19T13:45:22.865Z","dependency_job_id":"90db1e84-56ef-450b-b94e-34838d940983","html_url":"https://github.com/brittonhayes/aos","commit_stats":null,"previous_names":["brittonhayes/warhammer"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brittonhayes%2Faos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brittonhayes%2Faos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brittonhayes%2Faos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brittonhayes%2Faos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brittonhayes","download_url":"https://codeload.github.com/brittonhayes/aos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237834596,"owners_count":19373756,"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":["golang","jaeger","observability","open-telemetry","prometheus","tabletop","wargaming","warhammer"],"created_at":"2024-09-26T07:02:11.540Z","updated_at":"2025-10-23T13:30:49.172Z","avatar_url":"https://github.com/brittonhayes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AoS \n\n[![Go Reference](https://pkg.go.dev/badge/github.com/brittonhayes/aos.svg)](https://pkg.go.dev/github.com/brittonhayes/aos)\n[![Go Report Card](https://goreportcard.com/badge/github.com/brittonhayes/aos)](https://goreportcard.com/report/github.com/brittonhayes/aos)\n\n\u003e An unnoficial AoS REST API built with Go and Sqlite.\n\n## ⚡ Quick Start\n\nGet started with docker-compose to seed the database and start the API server.\n\n```sh\ndocker-compose up --build --force-recreate --remove-orphans --detach\n```\n\nor with [task](https://taskfile.dev/)\n\n```sh\ntask up\n```\n\n## 📖 Documentation\n\nAPI documentation is available in YAML format within the repository. The OpenAPI spec is used to generate the transport logic thanks to [goapi-gen](https://github.com/discord-gophers/goapi-gen).\n\n- [View the OpenAPI Spec](https://github.com/brittonhayes/aos/blob/main/api/openapi.yaml)\n\n## 🗄️ Adding or Editing Data\n\nAll application data used to seed the database is editable in the [fixtures/](https://github.com/brittonhayes/aos/blob/main/fixtures/) directory. The API is built to be self-seeding and read-only, so if there is a need to add more data, simply add it to the fixtures files, rebuild and redeploy the API.\n\n### Example - Adding a new alliance\n\nTo add a new entry to the database, just add a new object to the appropriate yaml fixtures file. In this case, `fixtures/alliances.yaml`. This processes is the same for all data types.\n\n```diff\n# fixtures/alliances.yaml\n    - model: GrandAlliance\n      rows:\n        - id: order\n          name: Order\n          description: The forces of Order strive to bring unity and stability to the Mortal Realms. Composed of various factions, they fight against the forces of Chaos.\n+       - id: chaos\n+         name: Chaos\n+         description: The forces of Chaos seek to corrupt and dominate the Mortal Realms. Made up of daemons, monsters, and twisted beings, they spread destruction wherever theygo.\n```\n\n- [View the data](https://github.com/brittonhayes/aos/blob/main/fixtures/)\n\n## API Endpoints\n\n*The API is read-only*\n\n✅=Available\n🚧=Under Construction\n\n- ✅ `/cities` - Get all cities\n- ✅ `/cities/{id}` - Get a city by ID\n- ✅ `/grand-alliances` - Get all grand alliances\n- ✅ `/grand-alliances/{id}` - Get a grand alliance by ID\n- ✅ `/grand-strategies/` - Get all grand strategies\n- ✅ `/grand-strategies/{id}` - Get a grand strategy by ID\n- ✅ `/units` - Get all units\n- ✅ `/units/{id}` - Get a unit by ID\n- ✅ `/warscrolls/` - Get all warscrolls\n- ✅ `/warscrolls/{id}` - Get a warscroll by ID\n- ✅ `/graphql` - GraphQL playground\n- ✅ `/query` - GraphQL query endpoint\n\n## 🔎 Querying\n\nThe API supports GraphQL queries. The GraphQL playground is available at `/graphql` and the query endpoint is available at `/query`.\n\n### Example - Get all units\n\n```graphql\nquery {\n  units {\n    id\n    name\n    description\n    grandAlliance\n    points\n  }\n}\n```\n\n### Example - Get all units, filtering for a specific name\n\n```graphql\nquery {\n  units(filter: { name: \"Lord\" }) {\n    id\n    name\n    description\n    grandAlliance\n    points\n  }\n}\n```\n\n## 📦 Go Client\n\nA Go client is available for the API. More examples are available in the [example/](https://github.com/brittonhayes/aos/tree/main/example) directory.\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"net/http\"\n\t\"time\"\n\n\t\"github.com/brittonhayes/aos/client\"\n)\n\nfunc main() {\n\t//\tSetup a context with a timeout so we're covered in case of a slow response\n\tctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)\n\tdefer cancel()\n\n\t// Create a new http client\n\tc := client.NewClient(\u0026http.Client{}, \"http://aos-api.localhost/query\", nil)\n\n\t// Get all allegiances\n\tresp, err := c.GetAllegiances(ctx, client.AllegianceFilters{})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// List the allegiances\n\tfor _, a := range resp.Allegiances {\n\t\tprintln(a.Name)\n\t}\n}\n```\n\n## 📈 Monitoring\n\nApplication observability is instrumented with OpenTelemetry. Telemetry is available in [Grafana](https://grafana.com/grafana/) and [Prometheus](https://prometheus.io/). Application tracing is powered by [Grafana Tempo](https://grafana.com/oss/tempo/). All application services are behind [Traefik](https://doc.traefik.io/traefik/) reverse proxy.\n\nWhen running with docker-compose, the following services are available:\n\n- API is available at [http://aos.localhost:8090](http://aos.localhost:8090)\n- Documentation is available at [http://aos.localhost:8090/docs](http://aos.localhost:8090/docs)\n- Traefik Dashboard is available at [http://localhost:8080](http://localhost:8080)\n- Prometheus is available at [http://prometheus.localhost:8090](http://prometheus.localhost:8090)\n- Grafana is available at [http://grafana.localhost:8090](http://grafana.localhost:8090)\n\n## 🙋 FAQ\n\n- **Q: Where is X {unit,alliance,etc}?** - A: Waiting for you to add it! See the [fixtures/](https://github.com/brittonhayes/aos/blob/main/fixtures/) directory for more information.\n\n## ⚖️ Copyright and Data Ownership\n\nThis project provides a self-hosted API solution for Warhammer Age of Sigmar data. We are in no way affiliated with Games Workshop, and all Warhammer Age of Sigmar data is the sole property of Games Workshop. \n\nAs the operator of your own instance of this API, you are responsible for:\n1. Reviewing and complying with Games Workshop's [Intellectual Property Guidelines](https://www.warhammer.com/en-GB/legal#IntellectualPropertyGuidlines)\n2. Ensuring your usage falls under the `Celebrating the Hobby` section of the agreement\n3. Not commercializing the data in any way\n4. Operating the API in accordance with Games Workshop's guidelines\n\nThis project aims to help users engage with the wonderful world of Warhammer in a programmatic way through a REST interface rather than the usual PDF format. Any changes to the data in your instance must respect the licensing rules documented by Games Workshop.\n\nFor more information, view our [Contributing Guidelines](https://github.com/brittonhayes/aos/blob/main/CONTRIBUTING.md).\n\n## Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrittonhayes%2Faos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrittonhayes%2Faos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrittonhayes%2Faos/lists"}