API Versioning & Integration Guidelines

This document covers how the StudentCrowd APIs evolve, what backward-compatibility guarantees we make, and how we communicate changes to customers and integration partners.

Our APIs are designed to be stable, predictable, backward compatible, and safe to upgrade.

Versioning

We use major-version URI versioning. The version segment appears in every endpoint path:

https://data.studentcrowd.net/api/v1.0/halls
https://data.studentcrowd.net/api/v1.0/room-types

The version in the URL identifies the API contract you integrate against. Within that version we only ship backward-compatible improvements. We introduce a new version only when a breaking change is unavoidable.

Backward Compatibility

Within a version, we maintain backward compatibility. Your integration should keep working as we ship improvements. These changes are non-breaking and can land at any time:

• New optional response fields
• New endpoints
• New optional request parameters
• New pagination metadata
• New enum values
• Performance improvements

Breaking Changes

The following require a new major version:

• Removing or renaming fields
• Changing response structures or field types
• Changing endpoint behaviour or semantics
• Authentication or authorisation changes
• Making optional fields required

Integration Best Practices

Follow these to stay compatible as the API evolves.

1. Ignore unknown fields

We will add fields over time. Your integration must not break when it encounters fields it doesn't recognise.

{
  "id": "123",
  "name": "University of Oxford",
  "new_field": "future value"
}

2. Don't rely on JSON field ordering

JSON property order is not guaranteed.

3. Handle enum values defensively

Don't assume enums are fixed. If status is "published" today, tomorrow it could include "pending", "archived", or "flagged". Handle unknown values gracefully.

4. Don't use strict schema validation

Rigid validation will break when we add optional fields. Validate what you need, ignore the rest.

Authentication & Security

Authentication is documented separately. If auth changes are needed, we will:

• Announce in advance
• Provide migration docs
• Give transition timelines

Deprecation Policy

Endpoints or fields may be deprecated over time. Deprecated functionality keeps working during the transition period.

Process

Step 1 — Announcement. We update docs, publish changelog entries, notify impacted customers, and provide migration guidance.

Step 2 — Deprecation period. Deprecated functionality stays available. Responses may include headers:

Deprecation: true
Sunset: Wed, 01 Nov 2027 00:00:00 GMT

Step 3 — Sunset. Removed only after the published sunset date.

Minimum notice

6–12 months for breaking changes, such as a new major API version. We may extend for critical integrations.

Notification Cadence

For every breaking change or deprecation, notifications are triggered automatically on the following schedule:

Feedback Loop

We want customers to be able to influence changes and flag problems early. If a change raises concerns for your integration — or you hit an unforeseen issue during a migration — you can:

• Reply directly to any change notification email
• Contact your account manager
• Email [email protected]

All feedback raised during a deprecation period is reviewed before the sunset date. Where a change creates a genuine problem for an integration, we will work with you on migration support or timeline extensions.

Version Upgrades

When a new major version ships:

1. Old versions stay available during migration
2. We provide migration guides with before/after examples
3. Updated docs and examples are published
4. Customers get advance notice before old versions are retired

Communicating Changes

We communicate API changes via:

• Documentation updates
• Email notifications (following the cadence above)
• Direct partner communications

For breaking changes, we also provide migration docs, updated endpoint references, deprecation timelines, and support contacts.