API tasarımı

Gereksinimlerden bir API'ye geçiş

Çoğu teknoloji gibi, bir API de bir sorunun çözümüdür. Doğru API'yi tasarlamak için, aşağıdaki soruları yanıtlayarak ele aldığınız sorunun açık bir şekilde tanımlandığından emin olmanız gerekir:

• Bu API'nin hedef tüketicileri kimlerdir?
• Tüketiciler API aracılığıyla ne tür bilgileri manipüle edecek?
• Tüketiciler API üzerinde hangi eylemleri gerçekleştirecek?

Örneğin, bir yemek teslimat şirketiyseniz, iş ortağı ağınız için teslimat hizmeti sağladığınız restoranların yer aldığı bir veritabanında gezinmelerini ve arama yapmalarını sağlayacak bir API oluşturmak isteyebilirsiniz.

Bu örnekte, API'niz şirketinizin iş ortaklarını hedeflemektedir. Restoranlar hakkındaki verileri işlemeleri ve belirli filtreleme ile sıralama özellikleri doğrultusunda bu veriler üzerinde arama sorguları gerçekleştirmeleri gerekecektir.

Başka bir örnek: Bir takvim SaaS şirketiyseniz, dünyadaki diğer ön uç geliştiricilerin takvim sisteminizi temel alan yeni mobil ve web uygulamaları oluşturabilmesi için bir API geliştirmek isteyebilirsiniz.

API'nizin tüketicilerini düşünmek, onlara iyi bir geliştirici deneyimi sunmanın ilk adımıdır. Bu, API'nizin öne çıkmasına ve etkileşim düzeylerini artırmasına yardımcı olacaktır.

Bir API'yi oluşturan öğeler

Bir API tasarlarken kullanılan dört temel kavram vardır:

• Bir Kaynak, tüketicilerinizin API'niz aracılığıyla etkileşim kuracağı bir öğedir. Kaynaklar, benzersiz bir şekilde bir yol ile tanımlanır; bu yol, API'nin uç noktasıyla birleştiğinde web'deki bir kaynak için benzersiz bir adres sağlar. Örneğin Calendars, bir takvim listesine karşılık gelen bir kaynağın adıdır ve yolu /calendars şeklindedir.
• Bir İşlem, kaynaklarınız üzerinde gerçekleştirilebilecek eylemdir. En yaygın işlemler GET (okuma), POST (oluşturma), PUT (güncelleme) ve DELETE'tir. Örneğin List all Calendars, Calendars kaynağında GET yöntemini kullanan bir işlemin adıdır.
• Bir Veri türü, ağ üzerinden aktarılan asıl verinin bir açıklamasıdır. Örneğin Calendar; adı, sahibi ve kendisine ait etkinliklere yönelik bir referans gibi bir Calendar'ın tüm özelliklerini tanımlayacak bir veri türünün adıdır. List all Calendars işlemi, Calendar veri türlerinin bir listesini döndürür.
• Bir Bileşen, API tanımı genelinde yeniden kullanılabilen bir öğedir. Örneğin, aynı sorgu parametresini birkaç işlemde kullanmanız gerekiyorsa, bunu bir bileşen olarak oluşturabilir ve gerektiği kadar çok işlemde buna referans verebilirsiniz.

Bir API'yi oluşturan başka kullanışlı ögeler de vardır:

• Bir Uç Nokta, API'nizin web üzerindeki ana giriş noktasıdır. Bir uç nokta, HTTPS gibi bir şemadan ve www.calendar-api.com gibi bir ana makineden oluşur.
• Bir Metin bloğu, API tasarımınızda herhangi bir yere yerleştirilebilecek herhangi bir metni (markdown dahil) serbestçe girmek için kullanılabilir. Kimlik doğrulama ve hata işleme gibi çapraz konuları açıklamak için metin bloklarını kullanın.
• Bir Bölüm, kaynakları ve veri türlerini anlamlı bir şekilde gruplandırmak için kullanılır. API tasarımınızı daha net ve geliştirici dostu hale getirmek için bunları kullanın. Öğeleri sol paneldeki bölümlere sürükle ve bırak yapabilir ve ayrıca bölümleri kendi aralarında yeniden sıralayabilirsiniz.

API Sözleşmeleri'nde, sağ üst köşedeki Yeni oluştur menüsünden bu öğeleri oluşturabileceksiniz.

Sunucu URL'leri genel bilgiler ekranında oluşturulur. Bir sunucu URL'si Yayımlandı veya Yayımlanmadı olabilir. Yayımlanmışsa Canlı Dokümantasyon'da görünür.