Kavramlar
Kapsam, sayfalama, arama parametreleri, enum tabloları, normalize
Hızlı Deneme
Kurulum gerektirmeyen en kolay yol — Swagger:
- /api/docs adresini açın.
- Sağ üstteki Authorize'a tıklayıp API anahtarınızı girin (
Bearerile). - Bir uca tıklayın → Try it out → gövdeyi düzenleyin → Execute. Yanıtı anında görürsünüz.
Postman / Insomnia tercih ederseniz, hazır dosya indirmenize gerek yok — güncel uç listesini doğrudan içe aktarın:
- Postman → Import → Link.
- Şu adresi yapıştırın:
https://metadata.libraryturk.com/swagger/v1/swagger.json - İçe aktarılan istekler her zaman günceldir (uçlar koddan üretilir). Authorization başlığına
Bearer <anahtarınız>ekleyin.
Çok-Kiracılı Kapsam
API anahtarınız yayıncı kapsamınızı belirler. Liste, arama ve detay uçları yalnız yetkili olduğunuz veriyi
(kendi yayınlarınız + alt yayıncılarınız) döndürür. Bazı alanlar (ör. documentId, telif/dağıtım
oranları) yalnız yayıncı kapsamında döner; genel/kurum tüketicisine dönmez.
Sayfalama
Liste uçları page ve pageSize (varsayılan 25, en çok 200) alır; yanıt
total, page, pageSize, items[] içerir.
Arama ucu (/search) ise page + limit kullanır; yanıt total ve hits[] döndürür.
Arama İstek Parametreleri (/search)
Gövde JSON; yalnız query tipik olarak yeterlidir, diğerleri filtre/sıralama içindir.
| Alan | Tip | Anlam |
|---|---|---|
query | string | Arama metni. Boş gönderilirse TÜM katalog (match_all) + facet'ler döner. En fazla 200 karakter. |
limit | number | Sonuç sayısı (varsayılan 25). |
page | number | Sayfa numarası (varsayılan 1). |
sort | string | Sıralama — geçerli değerler aşağıdaki tabloda. Varsayılan: alaka (relevance). |
publishers | string[] | Yayıncı adına göre filtre (yanıttaki facet 'publishers' değerleri). |
categories | string[] | Kategori adına göre filtre (facet 'categories'). |
languages | string[] | Dil koduna göre filtre (örn. TR, EN — facet 'languages'). |
mezo | string[] | Bilim dalı adına göre filtre (facet 'mezo'). |
subjects | string[] | Alt konu adına göre filtre (facet 'subjects'). |
years | number[] | Belirli yıllar (facet 'years'). |
yearMin / yearMax | number | Yıl aralığı (min–max). years yerine aralık vermek için. |
sort — geçerli değerler
| Değer | Anlam |
|---|---|
(boş) / relevance | Alaka skoruna göre (varsayılan) |
date-desc / newest | En yeni → en eski |
date-asc / oldest | En eski → en yeni |
alphabetical / az | Başlığa göre A → Z |
alphabetical-desc / za | Başlığa göre Z → A |
Karşılık (Enum) Tabloları
matchType (arama yanıtı)
Arama, girilen metni otomatik tanır; matchType hangi yolla eşleştiğini belirtir:
| Değer | Anlam |
|---|---|
Search | Serbest metin araması |
Isbn | Girdi ISBN olarak tanındı |
Doi | Girdi DOI olarak tanındı |
Orcid | Girdi ORCID olarak tanındı |
ISBN türü
| Değer | Anlam |
|---|---|
t | Basılı ISBN |
e | Elektronik (e-kitap) ISBN |
Otomatik Normalize
Tekil getirme uçları girdiyi otomatik temizler — önek/biçim takmanıza gerek yok:
| Alan | Kabul edilen biçimler |
|---|---|
| ISBN | 978-605-123-456-7, boşluklu veya tiresiz — hepsi normalize edilir |
| DOI | Çıplak 10.x/..., https://doi.org/... veya doi:... |
| ORCID | Çıplak 0000-0002-... veya https://orcid.org/... |
Kimlik (ID) Kaynakları
Filtrelerde kullanılan kimliklerin listesini ilgili uçlardan alırsınız:
| Kimlik | Listeleyen uç |
|---|---|
categoryId | POST /api/v1/categories |
languageId / dil kodu | POST /api/v1/languages |
subjectId (bilim dalı / mezo) | POST /api/v1/subjects |
| alt konu | POST /api/v1/subtopics |
Tarih Biçimi ve Yanıt
Tüm tarihler ISO 8601 (örn. 2026-01-15T00:00:00). Yanıtlar JSON · UTF-8.
Null veya yetkisiz alanlar yanıttan düşebilir. Arama yanıtındaki took alanı motorun sorgu süresini (ms) verir.