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ça tanımlandığından emin olmanız gerekir:

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

Örneğin, bir yemek teslimat şirketiyseniz, iş ortağı ağınız için teslimat hizmeti sunduğunuz restoranların veritabanına göz atmalarını ve arama yapmalarını sağlayacak bir API oluşturmak isteyebilirsiniz.

Bu örnekte, API'niz şirketinizin iş ortaklarını hedeflemektedir. Restoranlarla ilgili verileri işlemeleri ve belirli filtreleme ve sıralama yetenekleriyle 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 sisteminize dayalı yeni mobil ve web uygulamalar oluşturabilmesi için bir API oluşturmak isteyebilirsiniz.

API'nizin tüketicilerini düşünmek, onlara iyi bir geliştirici deneyimi sunmaya yönelik ilk adımdı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 tasarlanırken kullanılan dört temel kavram vardır:

• Bir Kaynak (Resource), tüketicilerinizin API'niz aracılığıyla etkileşime gireceği bir öğedir. Kaynaklar, API'nin uç noktasıyla birleştirildiğinde web'deki bir kaynak için benzersiz bir adres sağlayan bir yolla benzersiz şekilde tanımlanır. Örneğin, Takvimler (Calendars), takvimlerin listesine karşılık gelen bir kaynağın adıdır ve yolu /calendars şeklindedir.
• Bir İşlem (Operation), kaynaklarınız üzerinde gerçekleştirilebilecek eylemdir. En yaygın işlemler GET (okuma), POST (oluşturma), PUT (güncelleme) ve DELETE'tir (silme). Örneğin, Tüm Takvimleri Listele (List all Calendars), Takvimler kaynağında GET yöntemini kullanan bir işlemin adıdır.
• Bir Veri türü (Data type), ağ üzerinden alınıp verilen gerçek verilerin bir açıklamasıdır. Örneğin, Takvim (Calendar), bir Takvimin adı, sahibi ve ona ait etkinliklere bir referans gibi tüm özelliklerini açıklayacak bir veri türünün adıdır. Tüm Takvimleri Listele işlemi, Takvim veri türlerinin bir listesini döndürür.
• Bir Bileşen (Component), API tanımı boyunca 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 işlemde ona başvurabilirsiniz.

Bir API'yi oluşturan başka yararlı öğeler de vardır:

• Bir Uç nokta (Endpoint), web'deki API'niz için ana giriş noktasıdır. Bir uç nokta, HTTPS gibi bir şema ve www.calendar-api.com gibi bir ana bilgisayardan oluşur.
• Bir Metin (Text) 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 (Section), 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. Sol paneldeki bölümlere öğeleri sürükle ve bırak ile taşıyabilir ve ayrıca bölümleri kendi aralarında yeniden sıralayabilirsiniz.

API Designer içinde, bu öğeleri sağ üst köşedeki Yeni oluştur menüsünden oluşturabileceksiniz.

Sunucu URL'leri genel bilgiler ekranında oluşturulur. Bir sunucu URL'si Yayınlandı veya Yayınlanmadı olabilir. Yayınlanmışsa, Canlı Belgelerde görünür.