API lifecycle

This page is the contract about change itself: what we may alter without warning you, what earns a deprecation notice, and how long you have to act when something goes away. Write your integration against these rules and a routine platform release never breaks it.

The API is pre-launch. The published contract is a 0.x release, so the commitments below describe how the platform behaves from the 1.0 release onward, and the changelog records every change made in the meantime.

Key commitments

Commitment	What it means
Notice before an endpoint or field goes away	At least six months between the first Deprecation: true response header and the Sunset date. A shorter window needs a documented exception, such as a security cliff or no known consumers.
How you are told	The Deprecation, Sunset and Link response headers on the affected endpoint, a changelog entry, a migration page, and email to the technical contact on your client at first notice and again 90, 30 and 7 days before sunset.
Additive change without notice	New endpoints, new optional response fields and new values in a growable classification ship in the current version, at any time.
Nothing removed or renamed silently	A field we serve today keeps its name, type and meaning until it has been through the deprecation timeline above.
Data you already send keeps working	A value the API accepts in a request today stays accepted. Request validation is never tightened inside a version.

Keep a technical contact on your client current, because that address is where a deprecation notice goes. A client with no contact cannot be given notice, so onboarding requires one.

Versioning

The API carries no version segment in its paths. https://data.placepoint.no/properties/NO/0301-208-15-0-0 is the path today and stays the path: there is one API with one contract, and compatible growth happens in place rather than behind a new prefix. That is a deliberate choice, and it puts the weight on the compatibility rules below instead of on a migration every time the platform gains a field.

The OpenAPI contract itself is versioned with semantic versioning in info.version, and you can read the current value from the published contract. getOpenApiSpec serves the same file at /openapi.yaml once the platform answers.

• Patch for a documentation fix that leaves the served behavior alone.
• Minor for a backwards-compatible addition.
• Major for a breaking change, which also requires the deprecation timeline.

Every change to the contract bumps the version, and the version in the spec matches what the gateway serves. Pin nothing to the version string; use it to tell releases apart in the changelog.

What is backwards compatible

These changes ship without notice, and your client has to tolerate them:

• A new endpoint, or a new sub-resource under an existing one.
• A new optional field in a response. Ignore what you do not read, and never reject a response because it carries a property you do not recognize.
• A new value in a growable classification. Document.kind, Certification.scheme and the webhook event types are marked x-extensible-enum in the spec: the documented values are the ones we serve today, and more follow as new registers and schemes are connected. Map an unknown value to your own fallback rather than failing the parse.
• A new optional query parameter, or a new optional field in a request body.
• A relaxed validation rule: a longer maximum length, a wider numeric range, a looser pattern.
• A new response header.
• A new error code inside an HTTP status you already handle. Switch on the status first and the code second, and treat an unrecognized code as the generic case for that status.

Two consequences worth stating plainly. Parse defensively: an unknown field or an unknown classification value is normal traffic, not a fault. And order is not part of the contract: array order is only guaranteed where an endpoint documents it, and object key order never is.

What counts as breaking

A change is breaking when a correct client written against the old contract stops working. Removing or renaming a field, changing its type or its unit, removing a value from a classification, adding a required request parameter, tightening validation, changing an HTTP status for the same condition, or withdrawing an endpoint all qualify.

A breaking change never edits an endpoint in place. It ships as a new field beside the old one, or as a new resource, and the old surface stays up under the deprecation timeline until known consumers have moved. Continuous integration enforces this rather than trusting a reviewer: every change to the contract is diffed against the published version, and a breaking change fails the build unless it carries a major bump and a sunset date.

Deprecation and sunset

A deprecated endpoint or field says so on every response, following RFC 8594:

Deprecation: true
Sunset: Sat, 12 Nov 2026 00:00:00 GMT
Link: <https://docs.placepoint.no/developer/migrations/properties-owners-v1-to-v2>; rel="deprecation"
Link: <https://docs.placepoint.no/developer/migrations/properties-owners-v1-to-v2>; rel="successor-version"

• A deprecated field keeps being populated until the sunset date. It is marked deprecated: true in the spec, with the sunset date beside it, so a generated client can warn at compile time.
• After the sunset date the endpoint answers 410 Gone with a Problem Details body whose code is DEPRECATED_USE_SUCCESSOR, and a Link header pointing at the replacement.
• Every breaking change ships a migration page, linked from the header, the email and the changelog. It carries a side-by-side request and response, a table mapping each old field to its new one, and the timeline.

Watch for the Deprecation header in your own client and log it. It is the earliest signal you get, it arrives on traffic you are already making, and it names the successor.

What to do about all this

• Tolerate unknown fields and unknown classification values.
• Switch on the HTTP status, then the error code; never on a message string.
• Log the Deprecation and Sunset headers, and alert on them.
• Keep a technical contact current on your client.
• Read the changelog before you upgrade a client library.