An unnoficial AoS REST API built with Go and Sqlite.
Get started with docker-compose to seed the database and start the API server.
docker-compose up --build --force-recreate --remove-orphans --detach
or with task
task up
API documentation is available in YAML format within the repository. The OpenAPI spec is used to generate the transport logic thanks to goapi-gen.
All application data used to seed the database is editable in the 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.
To 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.
# fixtures/alliances.yaml
- model: GrandAlliance
rows:
- id: order
name: Order
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.
+ - id: chaos
+ name: Chaos
+ 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.
The API is read-only
β =Available π§=Under Construction
- β
/cities
- Get all cities - β
/cities/{id}
- Get a city by ID - β
/grand-alliances
- Get all grand alliances - β
/grand-alliances/{id}
- Get a grand alliance by ID - β
/grand-strategies/
- Get all grand strategies - β
/grand-strategies/{id}
- Get a grand strategy by ID - β
/units
- Get all units - β
/units/{id}
- Get a unit by ID - β
/warscrolls/
- Get all warscrolls - β
/warscrolls/{id}
- Get a warscroll by ID - β
/graphql
- GraphQL playground - β
/query
- GraphQL query endpoint
The API supports GraphQL queries. The GraphQL playground is available at /graphql
and the query endpoint is available at /query
.
query {
units {
id
name
description
grandAlliance
points
}
}
query {
units(filter: { name: "Lord" }) {
id
name
description
grandAlliance
points
}
}
A Go client is available for the API. More examples are available in the example/ directory.
package main
import (
"context"
"net/http"
"time"
"github.com/brittonhayes/aos/client"
)
func main() {
// Setup a context with a timeout so we're covered in case of a slow response
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// Create a new http client
c := client.NewClient(&http.Client{}, "http://aos-api.localhost/query", nil)
// Get all allegiances
resp, err := c.GetAllegiances(ctx, client.AllegianceFilters{})
if err != nil {
panic(err)
}
// List the allegiances
for _, a := range resp.Allegiances {
println(a.Name)
}
}
Application observability is instrumented with OpenTelemetry. Telemetry is available in Grafana and Prometheus. Application tracing is powered by Grafana Tempo. All application services are behind Traefik reverse proxy.
When running with docker-compose, the following services are available:
- API is available at http://aos.localhost:8090
- Documentation is available at http://aos.localhost:8090/docs
- Traefik Dashboard is available at http://localhost:8080
- Prometheus is available at http://prometheus.localhost:8090
- Grafana is available at http://grafana.localhost:8090
- Q: Where is X {unit,alliance,etc}? - A: Waiting for you to add it! See the fixtures/ directory for more information.
This 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.
As the operator of your own instance of this API, you are responsible for:
- Reviewing and complying with Games Workshop's Intellectual Property Guidelines
- Ensuring your usage falls under the
Celebrating the Hobby
section of the agreement - Not commercializing the data in any way
- Operating the API in accordance with Games Workshop's guidelines
This 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.
For more information, view our Contributing Guidelines.