GoSportsAPIDocs
Sign InGet API Key
Getting Started / Versioning

Versioning

The API version is part of the base URL. Within a version, changes are additive, so code you write today keeps working.

Current version

The current version is v1. It is part of the base URL:

https://api.gosportsapi.com/v1

How versioning works

The major version sits in the path of every request — /v1/football/fixtures. Changes that could break an existing integration are only released under a new major version with its own path. Your code keeps using the version in its base URL until you choose to move.

Within a version, the API only grows: new sports, endpoints, parameters and fields are added in place.

Breaking and non-breaking changes

Non-breaking — can ship within v1

  • New sports, endpoints and optional query parameters.
  • New fields in a response object.
  • New values in code fields such as status.short.
  • Changes to the order of fields in a JSON object.

Breaking — only in a new major version

  • Removing or renaming an endpoint, parameter or field.
  • Changing a field’s type or meaning.
  • Making an optional parameter required.
  • Changing how requests are authenticated.

Build tolerant clients

Ignore fields you don’t recognise and give unknown code values a sensible fallback. Then non-breaking changes never need a deploy.

const LABELS = { NS: "Not started", LIVE: "Live", HT: "Half-time", FT: "Full-time" };
// Fall back to the raw code for values added later
const label = LABELS[fixture.status.short] ?? fixture.status.short;

Deprecation

Before a version or an endpoint is retired, it is announced in the Changelog with at least [X months] notice, along with what changes and how to migrate. Until the retirement date it keeps working exactly as documented.

Staying up to date

  • Keep the base URL in one configuration value, so moving to a new version is a one-line change.
  • Follow the Changelog for new endpoints, fields and deprecations.
  • Check API Status for incidents and maintenance.
// config.js — the only place the version appears
export const API_BASE = "https://api.gosportsapi.com/v1";
// elsewhere
const res = await fetch(API_BASE + "/football/fixtures", {
  headers: { "x-api-key": process.env.GOSPORTS_API_KEY },
});