aos

AoS

An unnoficial AoS REST API built with Go and Sqlite.

✨ Try the API (hosted)

• API: https://aos-api.com/
• Documentation: https://aos-api.com/docs

⚡ Quick Start (self-hosted)

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

📖 Documentation

API documentation is available in YAML format within the repository. The OpenAPI spec is used to generate the transport logic thanks to goapi-gen.

• View the OpenAPI Spec

🗄️ Adding or Editing Data

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.

Example - Adding a new alliance

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.

• View the data

API Endpoints

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

🔎 Querying

The API supports GraphQL queries. The GraphQL playground is available at /graphql and the query endpoint is available at /query.

Example - Get all units

query {
  units {
    id
    name
    description
    grandAlliance
    points
  }
}

Example - Get all units, filtering for a specific name

query {
  units(filter: { name: "Lord" }) {
    id
    name
    description
    grandAlliance
    points
  }
}

📦 Go Client

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{}, "https://aos-api.com/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)
	}
}

📈 Monitoring (self-hosted)

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

🙋 FAQ

• Q: Where is X {unit,alliance,etc}? - A: Waiting for you to add it! See the fixtures/ directory for more information.

⚖️ Copyright and Data Ownership

Any changes to the data hosted by this repository must respect the licensing rules documented by Games Workshop here Intellectual Property Policy.

We are in no way affiliated with Games Workshop and the Warhammer Age of Sigmar data is the sole property of Games Workshop. We are abiding by their Celebrating the Hobby section of the agreement and not commercializing this data in any way. This API is purely to help allow users to engage with the wonderful world of Warhammer in a programattic way through a REST interface rather than the usual PDF.

If you consume the data served through this API, be aware that you are also obligated to respect Games Workshop's intellectual property guidelines.

For more information, view our Contributing Guidelines.

Contributors