API Versioninglink

The Infraspeak API uses URL-based versioning to ensure stability while allowing continuous improvement.

Current Versionlink

The current and recommended API version is v3.

Base URL: https://api.infraspeak.com/v3

Versioning Strategylink

URL-Based Versioninglink

The version is included in the URL path:

https://api.infraspeak.com/v3/locations
https://api.infraspeak.com/v3/failures
https://api.infraspeak.com/v3/elements

This approach provides:

• Clear version identification in every request.
• Ability to migrate gradually between versions.
• Explicit control over which version your integration uses.

Backwards Compatibilitylink

Within a major version (e.g., v3), we maintain backwards compatibility.

We do NOT expect to:

• Remove existing endpoints.
• Remove existing response fields.
• Change the type of existing fields.
• Change required request parameters to require different values.

We MAY:

• Add new endpoints.
• Add new optional request parameters.
• Add new fields to responses.
• Add new values to existing enums.
• Fix bugs (even if this changes behavior).

Version Lifecyclelink

Handling New Fieldslink

Your integration should gracefully handle new fields in responses. Use permissive JSON parsing that ignores unknown fields:

Pythonlink

import requests

response = requests.get(
    "https://api.infraspeak.com/v3/locations",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

# Access only the fields you need
for location in response.json()["data"]:
    # New fields won't break this code
    name = location["attributes"].get("name")
    code = location["attributes"].get("code")
    print(f"{code}: {name}")

JavaScriptlink

const response = await fetch("https://api.infraspeak.com/v3/locations", {
  headers: { "Authorization": "Bearer YOUR_TOKEN" }
});

const data = await response.json();

// Destructure only what you need
for (const location of data.data) {
  const { name, code } = location.attributes;
  console.log(`${code}: ${name}`);
}

PHPlink

$response = $client->get("https://api.infraspeak.com/v3/locations", [
    "headers" => ["Authorization" => "Bearer YOUR_TOKEN"]
]);

$data = json_decode($response->getBody(), true);

// Access specific fields without assuming structure
foreach ($data['data'] as $location) {
    $name = $location['attributes']['name'] ?? null;
    $code = $location['attributes']['code'] ?? null;
    echo "{$code}: {$name}\n";
}

Migration Guidancelink

When migrating to a new version:

1. Review changelog - Understand breaking changes and new features.
2. Test in sandbox - Validate your integration against the new version.
3. Update gradually - Migrate endpoints incrementally if needed.
4. Monitor deprecations - Track deprecated features in current version.

Deprecation Policylink

Before removing functionality:

1. Announcement - Deprecation notice at least 6 months before removal.
2. Documentation - Clear migration guides provided.
3. Warnings - Deprecated endpoints may return warning headers.
4. Support - Assistance available for migration questions.

Best Practiceslink

Pin Your Versionlink

Always specify the full versioned URL:

# Good - explicit version
BASE_URL = "https://api.infraspeak.com/v3"

# Avoid - no version
BASE_URL = "https://api.infraspeak.com"

Monitor API Changeslink

Check the API Changelog to stay informed about:

• New features and endpoints.
• Deprecation announcements.
• Breaking changes in upcoming versions.
• Bug fixes and improvements.

Test Before Upgradinglink

When migrating to a new version:

# Test the same endpoint on both versions
curl "https://api.infraspeak.com/v3/locations?limit=1" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq .

# Compare responses and update your code accordingly