tibiadata/tibiadata-api-go repository overview

⁠TibiaData API in Golang

TibiaData API written in Golang and deployed in container (version v3 and above).

Documentation of API endpoints can be found on docs.tibiadata.com⁠.

⁠Table of Contents

• API versions⁠
• How to use⁠
  • Helm⁠
  • Docker⁠
  • Docker-compose⁠
  • Local development⁠
  • Environment variables⁠
  • Deployment note⁠
• API documentation⁠
  • Available endpoints⁠
  • Deprecated endpoints⁠
  • Restricted endpoints⁠
• CI authentication⁠
• General information⁠
• Credits⁠

⁠API versions

Here is a summary of the TibiaData API versions

⁠How to use

You can either use it in a Docker container or go download the code and deploy it yourself on any server.

Keep in mind that there are restrictions on tibia.com that might impact the usage of the application being hosted yourself.

⁠Helm

We have a Helm chart available for you to use to deploy your application to Kubernetes.

All our charts are available through charts.tibiadata.com⁠.

Add the repository

helm repo add tibiadata https://charts.tibiadata.com
helm repo update

Search for the chart

helm repo search tibiadata

The charts-repository is located in tibiadata-helm-charts⁠.

⁠Docker

Our images are available on both GitHub Container Registry⁠ and Docker Hub⁠.

This is how to pull and run the latest release of TibiaData from GHCR⁠:

docker pull ghcr.io/tibiadata/tibiadata-api-go:latest
docker run -p 127.0.0.1:80:8080/tcp --rm -it ghcr.io/tibiadata/tibiadata-api-go:latest

You can also use Docker Hub⁠ to pull your images from.

If you want to run the latest code you can switch from latest to edge.

⁠Docker-compose

This is a simple example on how you can get up and running with TibiaData in docker-compose, which will be running on port 8080 and be exposed locally.

version: "3"

services:
  tibiadata:
    image: ghcr.io/tibiadata/tibiadata-api-go:latest
    restart: always
    environment:
      - TIBIADATA_HOST=tibiadata.example.com
    ports:
      - 8080:8080

⁠Local development

Build the code on your computer

docker build -t tibiadata .

Run your build locally

docker run -p 127.0.0.1:80:8080/tcp --rm -it tibiadata

⁠Environment variables

The following environment variables can be used to configure the API.

⁠Request correlation

Set TIBIADATA_LOG_CF_RAY=true to log Cloudflare's Cf-Ray header as request_id when present. Restrict origin access to Cloudflare so that clients cannot send arbitrary Cf-Ray values directly to the API.

⁠OpenTelemetry

Set TIBIADATA_OTEL_ENABLED=true to enable OpenTelemetry⁠ traces and metrics. When enabled, the API:

• creates a server span for each incoming request and continues traces from incoming W3C traceparent headers,
• creates client spans for upstream requests (e.g. to tibia.com) and propagates the trace context to them,
• records HTTP server and client metrics such as http.server.request.duration (request count, latency, method, route and status code),
• adds trace_id and span_id to request logs, so logs can be correlated with traces.

Probe endpoints (/ping, /health, /healthz, /readyz) are included in metrics but not traced.

All other settings use the standard OpenTelemetry environment variables⁠, for example:

A signal whose exporter is set to none creates no spans or measurements. When telemetry is disabled, or both exporters are none, no instrumentation is installed at all. For example, to collect only metrics:

TIBIADATA_OTEL_ENABLED=true
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0

⁠Deployment note

You should consider to add a layer in front of this application, so you can do caching of endpoints, access controll or what ever your needs are.

We do so at least by using Kong⁠ API Gateway, which solves features like caching, rate-limiting, authentication and more.

Successful data responses include a Cache-Control header with fixed, endpoint-specific cache lifetimes: characters and houses 300 seconds, guilds 120 seconds, highscores and news 900 seconds, and worlds 60 seconds. Both max-age and s-maxage use the configured lifetime; upstream Age, Date, and Last-Modified headers do not affect it. Set TIBIADATA_CACHE_CONTROL_HEADERS=false to disable them.

⁠API documentation

The hosted API documentation for our api.tibiadata.com⁠ service can be viewd at docs.tibiadata.com⁠.

There is a swagger-generated documentation available for download on the GitHub Release⁠ of the version you are looking for.

The official Tibia Fansite API OpenAPI specification⁠ is also available. Access to this API is limited to participants in Tibia's official Fansite Program.

⁠Available endpoints

Those are the current existing endpoints.

• GET /
• GET /ping
• GET /healthz
• GET /readyz
• GET /v4/boostablebosses
• GET /v4/character/:name
• GET /v4/creature/:race
• GET /v4/creatures
• GET /v4/fansites
• GET /v4/guild/:name
• GET /v4/guilds/:world
• GET /v4/highscores/:world/:category/:vocation/:page
• GET /v4/house/:world/:house_id
• GET /v4/houses/:world/:town
• GET /v4/killstatistics/:world
• GET /v4/news/archive
• GET /v4/news/archive/:days
• GET /v4/news/id/:news_id
• GET /v4/news/latest
• GET /v4/news/newsticker
• GET /v4/spell/:spell_id
• GET /v4/spells
• GET /v4/world/:name
• GET /v4/worlds
• GET /v5/boostablebosses
• GET /v5/character/:name
• GET /v5/creature/:race
• GET /v5/creatures
• GET /v5/fansites
• GET /v5/guild/:name
• GET /v5/guilds/:world
• GET /v5/highscores/:world/:category/:vocation/:page
• GET /v5/house/:world/:house_id
• GET /v5/houses/:world/:town
• GET /v5/killstatistics/:world
• GET /v5/news/archive
• GET /v5/news/archive/:days
• GET /v5/news/id/:news_id
• GET /v5/news/latest
• GET /v5/news/newsticker
• GET /v5/spell/:spell_id
• GET /v5/spells
• GET /v5/world/:name
• GET /v5/worlds
• GET /versions

⁠Highscore categories

On /v5/highscores, category aliases and case variants (for example magic, mlvl or MagicLevel) are answered with a 301 redirect to the canonical lowercase category name (for example magiclevel), so each category is served from a single cacheable URL. /v4/highscores keeps serving aliases directly. Unknown categories return HTTP 404 with JSON error 11004.

⁠Deprecated Endpoints

In addition to the deprecated API versions like v1, v2 and v3, there are also some endpoints that are deprecated. As of now, those are:

• GET /health

⁠Restricted endpoints

There are some endpoints that can be deviant between the container documentation and the hosted version. This is due to restricted mode that restrict certain API actions due to high load on the tibia.com servers.

• /v4/highscores and /v5/highscores-filtering on vocation is removed, only the all category is valid.

⁠Fansite API

The Fansite API allows you to access data provided by the official Tibia Fansite API using json and not by parsing HTML pages. To be able to use this you need to set a valid TIBIA_FANSITEAPI_TOKEN as an environment variable, which will be provided by CipSoft as part of their official Fansite program.

On startup, when a valid token is configured, the API performs a best-effort check against the Fansite API status endpoint⁠ and logs whether it currently reports as available. This check is purely informational and never prevents the application from starting, since it falls back to HTML scraping regardless.

The data returned by the HTML and JSON collector can differ, which may lead to discrepancies in the information provided by the two sources. Such findings are:

• Account achievements on the HTML page do not reflect the actual achievements grade as correctly shown by the JSON collector.

⁠CI authentication

The build and documentation workflows use the tibiadata-ci GitHub App to send cross-repository repository_dispatch events. Organization Actions variable TIBIADATA_CI_CLIENT_ID and secret TIBIADATA_CI_PRIVATE_KEY must be available to this repository. The app must be installed on tibiadata-api-docs, tibiadata-argocd-app-of-apps, and tibiadata-helm-charts with Contents: write permission.

Each dispatch creates a short-lived installation token restricted to its destination repository and Contents: write. The token is revoked at the end of the job. Other operations continue to use the workflow's GITHUB_TOKEN.

⁠General information

Tibia is a registered trademark of CipSoft GmbH⁠. Tibia and all products related to Tibia are copyright by CipSoft GmbH⁠.

⁠Credits

• Authors: Tobias Lindberg⁠ – List of contributors⁠
• Distributed under MIT License⁠