Apiary kapanıyor. Oracle, Apiary desteğinin sona erdiğine dair bir duyuru yayınladı ve API araçları alanındaki raporlar, barındırılan hizmetin nihai olarak Eylül 2026 civarında kapatılacağını gösteriyor. Site bugün hâlâ yükleniyor, ancak gidişat yıllardır belirgindi: Oracle, Apiary'yi Ocak 2017'de satın aldı, 2018'de ücretli planları kullanımdan kaldırdı ve çevreleyen açık kaynak araçların (Dredd, Gavel) arşiv durumuna düşmesine izin verdi. API dokümantasyonunuz apiary.io üzerinde yaşıyorsa, artık alternatifleri değerlendirmiyorsunuz. Geçiş yapıyorsunuz ve son tarih sizin değiştirebileceğiniz bir şey değil.
Doğrudan yanıt: Apidog, Apiary'nin yaptığı temel işleri (önce tasarıma dayalı spesifikasyon düzenleme, barındırılan interaktif belgeler ve sahte sunucu) karşılar. Ayrıca Apiary'nin tamamlayamadığı otomatik API testi, arşivlenmiş Dredd yerine spesifikasyon odaklı doğrulama ve CI entegrasyonu özelliklerini ekler. 4 kullanıcıya kadar ücretsizdir; ücretli planlar kullanıcı başına aylık 9 dolardan başlar. Tek önemli dezavantaj, Apidog'un API Blueprint dosyalarını doğrudan içe aktarmamasıdır. Bu nedenle Blueprint tabanlı projeleri önce OpenAPI'ye dönüştürmeniz gerekir.
Bu rehberde şunları uygulayacaksınız:
- Apiary verilerinizi dışa aktarmak
- API Blueprint'i OpenAPI'ye dönüştürmek
- Spesifikasyonu Apidog'a aktarmak
- Dokümantasyon, mock ve test akışlarını yeniden kurmak
Apiary'ye Gerçekten Ne Oluyor?
2011'de kurulan Apiary, tasarım öncelikli API iş akışını ürünleştiren araçlardan biriydi. OpenAPI öncesi dönemin Markdown tabanlı API açıklama formatı olan API Blueprint'i yaygınlaştırdı. Ayrıca Stripe'ın popülerleştirdiği üç sütunlu API dokümantasyon düzeni, barındırılan mock sunucular, GitHub senkronizasyonu ve Dredd ile Gavel açık kaynak araçlarını sundu.
Oracle, Apiary'yi Ocak 2017'de satın aldıktan sonra ürün uzun bir sessiz döneme girdi:
- Ücretli planlar 2018'de kaldırıldı.
- Yeni özellik geliştirme durdu.
- Dredd ve Gavel arşivlendi.
- Barındırılan hizmetin Eylül 2026 civarında kapanması bekleniyor.
Bump.sh, Apiary kullanıcıları için yayımladığı veda yazısında kritik noktayı açıkça belirtiyor: Kapanıştan önce API açıklamalarınızı dışa aktarın. Hizmet kapandıktan sonra dışa aktarılacak bir veri kalmayabilir.
Bu durumun iki pratik sonucu vardır:
- Yalnızca Apiary içinde bulunan API açıklamaları, dokümantasyon metinleri ve ekip ayarlarını hemen dışa aktarmalısınız.
- API Blueprint'in aktif olarak sürdürülen bir ardıl ekosistemi olmadığı için hedef formatınız OpenAPI olmalıdır.
Yerine Koymanız Gereken Bileşenler
Geçiş hedefini seçmeden önce Apiary'nin ekibiniz için hangi görevleri karşıladığını listeleyin:
- Tasarım öncelikli spesifikasyon düzenleyici: Tarayıcıda API Blueprint veya OpenAPI 3.0 yazıyor, belgeleri canlı güncelliyordunuz.
- Barındırılan interaktif dokümantasyon: apiary.io adreslerinde örnek isteklerle API referansı yayımlıyordunuz.
- Mock sunucu: Spesifikasyondaki örnek yanıtları tüketicilere sunuyordunuz.
- GitHub senkronizasyonu: Spesifikasyon dosyasını depoda tutuyor ve senkronize ediyordunuz.
- Dredd ile sözleşme testi: Gerçek uygulamayı spesifikasyona karşı çalıştırıyor ve sapmaları tespit ediyordunuz.
Dredd artık arşivlenmiş durumda. Yerine geçecek doğrulama yaklaşımı için Dredd olmadan API'nizi spesifikasyonuna göre nasıl doğrularsınız rehberine bakabilirsiniz.
Geçişte yalnızca bir dokümantasyon oluşturucu seçmeyin. Tasarım, dokümantasyon, mock ve doğrulama işlevlerini birlikte karşılayan bir platform seçin.
Cevap: Apidog
Apidog, 500.000'den fazla geliştirici tarafından kullanılan bir API geliştirme platformudur. Tasarım, dokümantasyon, mocking, hata ayıklama ve otomatik testi tek bir spesifikasyon etrafında birleştirir.
Apiary geçişi açısından önemli noktalar:
- Tasarım öncelikli iş akışı
Apidog, OpenAPI 3.x için hem görsel spesifikasyon düzenleyicisi hem de kod düzenleyicisi sunar. Uç noktaları, şemaları ve örnekleri bir kez tanımlarsınız. Dokümantasyon, mock sunucular ve testler bu tanımdan çalışır.
- Barındırılan ve interaktif dokümantasyon
Dokümantasyonunuzu çalışan bir “deneyin” konsoluyla yayımlayabilir, özel alan adı kullanabilir ve sürümleme uygulayabilirsiniz. Böylece dokümantasyon URL'leriniz yalnızca platformun varsayılan alan adına bağlı kalmaz.
- Şema farkında mock sunucu
Apiary'nin mock sunucusu genellikle yazdığınız örnekleri döndürüyordu. Apidog'un akıllı mock sunucusu, spesifikasyonunuzdaki şemalara göre gerçekçi yanıtlar üretebilir. Gerekli durumlarda özel mock kuralları da ekleyebilirsiniz.
- Dredd yerine sözleşme doğrulama
Apidog test senaryoları gerçek uygulamanıza istek gönderir ve yanıtları OpenAPI şemalarına göre doğrular. Testleri assertion'larla genişletebilir, veriye dayalı çalıştırabilir ve Apidog CLI ile CI ortamında çalıştırabilirsiniz.
Dokümantasyon ayrıca MCP sunucusuyla yayımlanabilir. Böylece yapay zekâ ajanları spesifikasyonunuzu doğrudan okuyabilir. Ayrıntılar için Apidog MCP Sunucusu nedir? makalesine göz atın.
Apiary'den Adım Adım Geçiş
Apiary geçişinde ek bir format dönüşümü adımı vardır: Apidog, API Blueprint'i doğrudan içe aktarmıyor.
Apidog içe aktarma dokümantasyonuna göre desteklenen kaynaklar şunlardır:
- Swagger 2.0
- OpenAPI 3.0 ve 3.1
- Postman koleksiyonları
- HAR
- RAML
- JMeter
- apiDoc
- I/O Docs
- WADL
- Google Discovery
API Blueprint listede olmadığı için önce OpenAPI'ye dönüştürmeniz gerekir.
1. Apiary'den Her Şeyi Dışa Aktarın
Her Apiary projesi için API açıklamasını düzenleyiciden indirin.
Proje GitHub ile senkronizeyse:
git clone https://github.com/kurumunuz/api-deponuz.git
cd api-deponuz
git pull origin main
Ardından depodaki spesifikasyonun Apiary'deki son sürümle eşleştiğini doğrulayın.
OpenAPI 3.0 formatında yazılmış daha yeni Apiary projeleriniz varsa dönüşüm adımını atlayabilirsiniz.
İlk işiniz tüm dışa aktarmaları tamamlamak olmalı. Bu, kapanış tarihine bağlı olan tek adımdır.
2. API Blueprint'i OpenAPI'ye Dönüştürün
Aşağıdaki araçlardan birini kullanabilirsiniz:
-
api-spec-converter: API Blueprint'ten doğrudan OpenAPI dönüşümü -
apib2swagger: Blueprint'ten Swagger/OpenAPI dönüşümü -
openapi-format: Çıktıyı normalleştirmek veya OpenAPI 3.1'e yükseltmek için
Örnek bir dönüşüm akışı:
api-spec-converter \
--from api_blueprint \
--to openapi_3 \
api.apib \
> openapi.yaml
Dönüşüm sonrası spesifikasyonu lint edin:
vacuum lint openapi.yaml
Özellikle şu iki alanı elle kontrol edin:
- Kimlik doğrulama şemaları: API Blueprint bunları resmi ve tutarlı biçimde modellemediği için dönüştürücü eksik sonuç verebilir.
- Markdown içindeki açıklamalar: Endpoint açıklamalarının dışında kalan serbest metin bölümleri OpenAPI alanlarına tam olarak taşınmayabilir.
Örneğin, dönüşümden sonra güvenlik şemasını OpenAPI'ye açıkça ekleyin:
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
Her API için bir saatlik inceleme planlayın. Çoğu proje için bu, haftalar sürecek bir yeniden yazım değildir.
3. OpenAPI Dosyasını Apidog'a Aktarın
Apidog içinde şu adımları uygulayın:
- Proje Ayarları bölümünü açın.
- Manuel İçe Aktarma seçeneğini seçin.
- OpenAPI dosyanızı yükleyin veya bir URL üzerinden içe aktarın.
- Endpoint, şema, örnek ve gruplamaları kontrol edin.
- Dokümantasyonu ve mock URL'sini test edin.
İçe aktarma sonrası referans belgeleri hemen oluşur. Akıllı mock sunucusu da içe aktarılan endpoint'ler için kullanılabilir.
4. Apiary'nin Karşılamadığı Akışları Yeniden Kurun
Geçiş yalnızca spesifikasyon aktarımı değildir. Aşağıdaki işleri de tamamlayın:
- Dokümantasyon için özel alan adı yönlendirin.
- Apiary mock URL'sini kullanan ekipleri yeni mock temel URL'si hakkında bilgilendirin.
- Dredd kontrollerini Apidog test senaryoları olarak yeniden oluşturun.
- Testleri yerelde ve CI ortamında çalıştırın.
Örnek CI akışı:
name: API Contract Tests
on:
pull_request:
push:
branches:
- main
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Apidog CLI ile testleri çalıştır
run: |
apidog-cli run \
--project-id "$APIDOG_PROJECT_ID" \
--token "$APIDOG_TOKEN"
Tek bir API projesi, dönüşüm dahil genellikle bir öğleden sonra taşınabilir. Birden fazla Blueprint API içeren portföylerde en çok zamanı genellikle kimlik doğrulama şemalarının manuel doğrulaması alır.
Apiary ve Apidog Karşılaştırması
| Apiary (bugün) | Apidog | |
|---|---|---|
| Gelecek | Kapanıyor; destek sonlandırıldı, hizmetin Eylül 2026 civarında sona ermesi bekleniyor | Aktif olarak geliştiriliyor |
| Spesifikasyon formatı | API Blueprint, daha sonra OpenAPI 3.0 | OpenAPI 3.x; Swagger 2.0 içe aktarma, görsel ve kod düzenleyiciler |
| Barındırılan belgeler | Evet, apiary.io URL'lerinde | Evet, özel alan adı, sürümleme ve “deneyin” konsolu |
| Mock sunucu | Yazılmış örnekleri yeniden oynatır | Şema farkında akıllı mock sunucular ve özel kurallar |
| Sözleşme testi | Dredd (arşivlendi) | Dahili test senaryoları, şema doğrulama ve CLI ile CI |
| Otomatik test paketleri | Hayır | Evet, görsel senaryolar, veriye dayalı testler ve sınırsız çalıştırma |
| GitHub senkronizasyonu | Evet | URL veya dosyadan spesifikasyon içe aktarma/senkronizasyon; şube tabanlı sürümleme |
| Fiyat | Ücretsiz; ücretli planlar 2018'de kaldırıldı | 4 kullanıcıya kadar ücretsiz, ardından kullanıcı başına aylık 9 dolar |
| Dışa aktarma yolu | API Blueprint / OpenAPI indirme | OpenAPI, Markdown ve HTML dışa aktarımları |
Ücretsiz Bir Aracı Değiştirmenin Maliyeti Nedir?
Apiary'nin kalan en güçlü yönü ücretsiz olmasıydı. Bu nedenle karşılaştırmayı yıllık maliyet üzerinden yapmak gerekir.
| Ekip büyüklüğü | Apidog yıllık | SwaggerHub Team yıllık | ReadMe Pro yıllık |
|---|---|---|---|
| 3 kişi | 0 $ — ücretsiz plan | 1.240 $ | 3.000 $ |
| 5 kişi | 540 $ | 2.066 $ | 3.000 $ |
| 10 kişi | 1.080 $ | 4.133 $ | 3.000 $ |
| 25 kişi | 2.700 $ | 10.332 $ | 3.000 $ |
Yalnızca ücretsiz spesifikasyon üretimi istiyorsanız, dokümantasyon odaklı araçların da ücretsiz katmanları bulunur. Ancak Apiary'yi ilk etapta faydalı yapan mock, test ve ekip işbirliğini de korumak istiyorsanız, bütünleşik bir platform daha anlamlıdır.
Apidog'un ücretsiz planı 4 kullanıcıya kadar bu iş akışlarını kapsar. Bu nedenle birçok küçük ekip için geçiş maliyeti yalnızca dönüşüm ve doğrulama için harcanan zamandır.
Apidog Uygun Değilse
“Apiary kullanmaya devam etmek” artık bir seçenek değil. İhtiyacınıza göre şu alternatifleri değerlendirebilirsiniz:
Yalnızca dokümantasyon oluşturmak istiyorsanız: Spesifikasyon başka bir araçta üretiliyor ve test ediliyorsa, Bump.sh gibi dokümantasyon öncelikli bir ürün uygun olabilir. Yine de API Blueprint'i OpenAPI'ye dönüştürmeniz gerekir.
SmartBear ekosisteminde standartlaşıyorsanız: SwaggerHub, Apiary'nin barındırılan spesifikasyon kayıt defteri yaklaşımına en yakın seçeneklerden biridir. Kullanıcı başına maliyet ve ölçülü test yürütmelerini değerlendirin. Daha fazla ayrıntı için en iyi SwaggerHub alternatifi makalesine bakın.
Büyük ekiplerde tasarım yönetişimine odaklanıyorsanız: Stoplight, stil kılavuzu ve yönetişim araçlarıyla öne çıkar. Karşılaştırma için en iyi Stoplight alternatifi rehberini inceleyin.
API Blueprint'i korumak istiyorsanız: Bunu yapmayın. Formatın araçları bakımsız, onu geliştiren şirket kapanıyor ve OpenAPI fiili standart hâline geldi. Bir kez dönüştürün ve sürdürülen ekosisteme geçin. API Blueprint kılavuzu tarihsel referans olarak yararlı olabilir.
Sıkça Sorulan Sorular
Apiary Tam Olarak Ne Zaman Kapanıyor?
Oracle, forumlarında Apiary desteğinin sona erdiğini duyurdu. API araç satıcılarından gelen güncel raporlar, barındırılan hizmetin Eylül 2026 civarında kapanacağını gösteriyor.
Güvenli yaklaşım basittir: Şimdi dışa aktarın. Ürünün tüm bileşenleri zaten bakımsız durumda.
Apidog, API Blueprint Dosyalarını Doğrudan İçe Aktarabilir mi?
Hayır. Apidog; OpenAPI/Swagger, Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL ve Google Discovery formatlarını içe aktarır.
API Blueprint'i önce api-spec-converter veya apib2swagger gibi bir araçla OpenAPI'ye dönüştürün. Ardından çıktıyı lint edin ve kimlik doğrulama şemalarını elle doğrulayın.
Apiary Mock Sunucusunun Yerini Ne Alıyor?
Apidog'un dahili akıllı mock sunucusu.
Apiary yazdığınız örnekleri döndürürken, Apidog şemalarınızdan otomatik olarak gerçekçi yanıtlar üretebilir. Belirli durumlar için özel mock kuralları da tanımlayabilirsiniz.
Sözleşme Testi İçin Dredd'in Yerini Ne Alıyor?
Apidog otomatik test senaryoları.
Bu senaryolar:
- Uygulamanıza gerçek istekler gönderir.
- Yanıtları spesifikasyon şemalarına göre doğrular.
- Assertion eklemenize izin verir.
- CI içinde Apidog CLI üzerinden çalışır.
Apidog Küçük Bir Ekip İçin Gerçekten Ücretsiz mi?
Evet. Ücretsiz plan; spesifikasyon düzenleyicileri, yayımlanmış interaktif belgeler, akıllı mock sunucu ve API testini 4 kullanıcıya kadar kapsar.
4 kullanıcının üzerinde kullanıcı başına aylık 9 dolar ücretlendirilir.
Bugün Dışa Aktarın, Hiçbir Şeyi Yeniden Tasarlamayın
İşlem sırası önemlidir:
- Önce Apiary'den dışa aktarın.
- API Blueprint'i OpenAPI'ye dönüştürün.
- Spesifikasyonu doğrulayın.
- Hedef platformu değerlendirin ve içe aktarın.
- Dokümantasyon, mock ve CI testlerini yeniden bağlayın.
İlk iki adımın son tarihi vardır; hedef platform seçiminin yoktur. Bu nedenle API verilerinizi önce güvenceye alın.
Hazır olduğunuzda OpenAPI dosyanızı Apidog'a aktarın ve dokümantasyon, mock sunucular ile test akışlarını aynı gün içinde çalışır duruma getirin.
Top comments (0)