Her API'nin kimsenin baştan sona okumadığı bir dokümantasyonu vardır. Bir OpenAPI spesifikasyonu; path'leri, metotları, istek ve yanıt yapılarını ve bunların üzerinde çalıştığı kaynakları anlatan yüzlerce satır olabilir. Kesin ve eksiksizdir, ama kafanda tutması neredeyse imkansızdır. Yeni bir servise düştüğünde aslında istediğin şey bir resimdir: ana kaynaklar neler, hangi endpoint'ler onlara dokunuyor ve hepsi nasıl bir araya geliyor?
O resim spesifikasyonun içinde zaten saklı. Bir OpenAPI ya da benzeri doküman yapılandırılmış veridir; yani bir araç onu okuyup, aksi halde elle yeniden kurman gereken yapıyı çizebilir.
Spesifikasyonun sana zaten söyledikleri
İyi biçimlendirilmiş bir API dokümanı göründüğünden daha fazla yapı içerir. Ondan şunları çıkarabilirsin:
- Kaynaklar: şemalardan ve path segmentlerinden (users, orders, products).
- İşlemler: her path'teki metotlardan (listele, oluştur, güncelle, sil).
- İlişkiler: şema referanslarından (bir Order bir User'a ve Line Item'lara referans verir).
- Gruplama: genellikle servisin gerçek modüllerine karşılık gelen tag'lerden.
Bunu metin olarak okumak yavaştır. Diyagram olarak görmek ise anında olur ve "ha, demek böyle birbirine oturuyor" anı diyagramda yaşanır.
İş akışı
Gerçekten yapıştır ve geç. Araca OpenAPI dokümanını ver; kaynakları ve ilişkileri çıkarır ve düzenlenebilir şekiller olarak yerleştirir. Sonrası bildiğin biçimlendirme: tag'e göre grupla, çekirdek kaynağı vurgula, bu diyagram için gürültü olan endpoint'leri gizle.
API'nin doğruluk kaynağı spesifikasyondur. Diyagramı ondan oluşturmak, resimle sözleşmenin birbiriyle çelişemeyeceği anlamına gelir.
API mimari diyagramını neden çizmek yerine türetmelisin
Bir API diyagramını elle çizebilirsin; biri yeni bir endpoint eklediği anda da yanlış olur. Onu spesifikasyondan türetmek resmi sözleşmeye bağlar. API değiştiğinde yeniden oluşturursun ve diyagram saniyeler içinde yine güncel olur. Gelişen bir servis için bu, insanların güvendiği dokümantasyonla sessizce görmezden geldiği dokümantasyon arasındaki farktır.
Tek bir servisin ötesinde
Aynı fikir büyük ölçekte de çalışır. Her biri kendi spesifikasyonuna sahip birkaç servisin varsa daha üst düzey bir harita kurabilirsin: hangi servis hangi kaynakların sahibi ve biri diğerini nerede çağırıyor. Bu, kimsenin elle güncel tutmaya asla vakit bulamadığı diyagramdır ve bir olay sırasında tam olarak bir öğleden sonranı kurtaran da odur. Bırak spesifikasyonlar çizsin, sonra onu ekibinin ihtiyaç duyduğu görünüme dönüştür.
Bir servisi anlamak için YAML okumayı bırak. Spesifikasyonu yapıştır ve onun yerine resmi oku.