API contract rules

Read the rules for base URLs, headers, authentication, coordinates, pagination and safe retries.

Last updated: 10 November 2026

On this page

Base URL and authentication Headers and formats Identifiers and date values Coordinates Pagination and cursors Writes, versions and retries Rate limiting and error handling

Base URL and authentication

The base URL is your organisation's application origin. External integration paths are under /api/v1; read-only data and map services are under /api/ogc. Use HTTPS. In examples, SOSOMAPS_URL represents your environment's URL and ERISIM_ANAHTARI the secret retrieved from secure configuration.

v1 business endpoints require Authorization: Bearer ERISIM_ANAHTARI. GET /api/v1/docs and GET /api/v1/openapi.json are public. OGC accepts the key in the Basic password field as well as Bearer authentication; cookie-authenticated application endpoints have separate session requirements. Authentication explains the scope model.

Headers and formats

Field	Meaning
`Content-Type: application/json`	Content type of a JSON write body. For uploads, use the endpoint's multipart contract.
`X-GIS-API-Surum`	Contract version header in v1 and OGC responses.
`X-GIS-Surum`	Version of the responding application.
`Cache-Control: no-store`	Indicates that these responses must not be stored in an HTTP cache.
`Retry-After`	Number of seconds to wait before retrying after a `429` response.

Field names are stable throughout the version. Use the JSON keys exactly as shown. Omitting a field is not the same as explicitly sending null; for example, null in editing props can remove an attribute. Check each endpoint's request schema.

Identifiers and date values

Project and user identifiers are numeric. Map feature, equipment, connection and circuit identifiers are strings; do not treat examples such as DOL-123 as a rule for generating identifiers. Obtain permanent identifiers from server responses. Do not match different entity types using only their numeric suffix.

The change stream's id and cursor are numeric identifiers. Handle date-time values as ISO 8601 values with a time zone, for example 2026-11-10T09:00:00+00:00. Do not discard the zone and assume local time. You may convert to local time for display; preserve the instant when storing it.

Coordinates

v1 GeoJSON geometries use WGS 84. Point coordinate order is longitude, latitude; bbox order is minLongitude,minLatitude,maxLongitude,maxLatitude. geometry.type must match a geometry accepted by the selected feature type.

For OGC, also consider the coordinate systems advertised by the collection and the Content-Crs response header. WMS 1.3.0 uses latitude, longitude order in an EPSG:4326 bounding box; do not copy the GeoJSON coordinate order into that request. Follow the examples in OGC services.

Pagination and cursors

In feature and technical-record lists, limit is the requested page size. after carries the last returned identifier; pass the response's next value unchanged into the next request. next: null indicates the last page. Keep filters unchanged between pages. The project list returns a direct array and does not use this envelope.

The cursor in a features response is a change identifier captured before the feature query. Save the first page's value. Tracking changes from that point after completing pagination lets you account for intervening writes. Process stream rows in increasing id order and advance only to the last identifier you have successfully applied.

Module visibility may replace before and after with gizli: true. Do not treat that row as a visible deletion. Rebuild the local view from the current scope whenever user permissions or key scope change.

Writes, versions and retries

POST /api/v1/projects/{pid}/edit applies the ops list in one transaction. request_id is required. Retrying the same operations with the same request_id for the same user and project returns the saved result; a different operation list is rejected with 409. Retry records are not retained indefinitely, and this behaviour does not apply to every POST endpoint.

Send the last-read version as version when updating or deleting. A map feature's version is in GeoJSON properties.v. If a stale version is rejected, reread the record and review your change against the current data. Do not assign a guessed new version number.

A lost response does not mean a write failed. Generating a new request_id for the same work risks duplicate records. See Concurrency and Editing API.

Rate limiting and error handling

A request counter rejection returns 429. Read the seconds in Retry-After and do not retry automatically before that wait ends. v1 and OGC share the same per-key counter. This document does not promise a numeric request-rate threshold.

The error body's detail may be a string or a validation array. Interpret kod and alan with the HTTP status; an unfamiliar code does not make a request successful. The Error codes glossary explains the client's next steps.