API sözleşme kuralları

Temel adres, başlık, kimlik, koordinat, sayfalama ve tekrar güvenliği kurallarını birlikte okuyun.

Son güncelleme: 2026-11-10

Temel adres ve kimlik

Temel adres kurumunuzun uygulama kaynağıdır. Dış entegrasyon yolları /api/v1, salt okunur veri ve harita yayını /api/ogc altında yer alır. HTTPS kullanın. Örneklerdeki SOSOMAPS_URL kendi ortamınızın adresini, ERISIM_ANAHTARI güvenli yapılandırmadan alınan sırrı temsil eder.

v1 iş uçlarında Authorization: Bearer ERISIM_ANAHTARI gerekir. GET /api/v1/docs ve GET /api/v1/openapi.json kimliksiz okunur. OGC, Bearer yanında Basic parola alanındaki anahtarı da kabul eder; çerezli uygulama uçlarının oturum gereksinimi ayrıdır. Kimlik doğrulama sayfası kapsam modelini açıklar.

Başlıklar ve biçimler

Alan adları sürüm boyunca değişmez. Örneklerdeki JSON anahtarlarını aynen kullanın. Gönderilmeyen bir alanın anlamı ile açık null aynı değildir; örneğin düzenleme props içinde null, ilgili özniteliği kaldırabilir. Her uç için istek şemasını kontrol edin.

Kimlik ve tarih değerleri

Proje ve kullanıcı kimlikleri sayısaldır. Harita nesnesi, cihaz, bağlantı ve devre kimlikleri metindir; DOL-123 gibi örnekleri biçim üretme kuralı kabul etmeyin. Kalıcı kimlikleri sunucunun yanıtından alın. Birden fazla varlık türünü yalnız sayısal son ekine göre eşleştirmeyin.

Değişiklik akışındaki id ve cursor sayısal kimliklerdir. Tarih-saat değerlerini saat dilimi içeren ISO 8601 değerleri olarak işleyin; örnek 2026-11-10T09:00:00+00:00. Saat dilimini çıkararak yerel saat varsaymayın. Kullanıcıya gösterirken yerel saate dönüştürebilirsiniz; saklarken an bilgisini koruyun.

Koordinatlar

v1 GeoJSON geometrileri WGS 84 kullanır. Nokta koordinat sırası boylam, enlem, bbox sırası minBoylam,minEnlem,maxBoylam,maxEnlem olur. geometry.type, çizdiğiniz nesne türünün kabul ettiği geometriyle uyumlu olmalıdır.

OGC’de koleksiyonun ilan ettiği koordinat sistemleri ve Content-Crs yanıtı ayrıca değerlendirilir. WMS 1.3.0 EPSG:4326 kutusunda sıra enlem, boylamdır; GeoJSON örneğinin sırasını aynen bu isteğe taşımayın. OGC yayını sayfasındaki örnekleri izleyin.

Sayfalama ve imleç

Nesne ve teknik kayıt listelerinde limit istenen sayfa boyudur. after son dönen kimliği taşır; yanıttaki next değerini değiştirmeden sonraki isteğe aktarın. next: null son sayfayı gösterir. Süzgeçleri sayfalar arasında sabit tutun. Proje listesi doğrudan dizi döndürür; bu zarfı kullanmaz.

features yanıtındaki cursor, nesne sorgusundan önce alınmış değişiklik kimliğidir. İlk sayfanın değerini saklayın. Sayfalar tamamlandıktan sonra değişiklikleri bu noktadan izlemek, aradaki yazmaları değerlendirmenize olanak verir. Akış satırlarını artan id sırasıyla işleyin ve yalnız başarıyla uyguladığınız son kimliği ilerletin.

Modül görünürlüğü nedeniyle before ve after yerine gizli: true bulunabilir. Bu satırı görünür bir silme işlemiyle eşitlemeyin. Kullanıcı yetkisi veya anahtar kapsamı değiştiğinde yerel görünümü güncel kapsamdan yeniden kurun.

Yazma, sürüm ve tekrar

POST /api/v1/projects/{pid}/edit, ops listesini bir işlem olarak uygular. request_id zorunludur. Aynı kullanıcı ve projede aynı request_id ile aynı işlemler tekrar gönderildiğinde kayıtlı sonuç döner; farklı işlem listesi 409 ile reddedilir. Tekrar saklama süresiz değildir ve diğer POST uçlarına genellenmez.

Güncelleme veya silmede okuduğunuz sürümü version olarak gönderin. Harita nesnesinin sürümü GeoJSON içinde properties.v alanındadır. Eski sürüm reddedildiğinde kaydı yeniden okuyun ve değişikliğinizi güncel veriyle değerlendirin. Körlemesine yeni sürüm sayısı atamayın.

Sunucunun yanıtı kaybolursa yazmanın yapılmadığını varsaymayın. Aynı iş için yeni request_id üretmek çift kayıt riski doğurur. Ayrıntılar Eşzamanlılık ve Düzenleme API’si sayfalarındadır.

Oran sınırı ve hata işleme

İstek sayacı dolduğunda 429 döner. Retry-After başlığındaki saniye değerini okuyun ve bekleme tamamlanmadan otomatik yeniden denemeyin. v1 ve OGC aynı anahtar sayacını paylaşır. Bu belgede sayısal oran eşiği taahhüt edilmez.

Hata gövdesindeki detail metin veya doğrulama dizisi olabilir. kod ve alan değerlerini HTTP durumuyla birlikte yorumlayın; anlamadığınız yeni bir kodda da isteği başarı saymayın. Hata kodları sözlüğü istemcinin sonraki adımını açıklar.