Sözleşmesi, sürümü ve belgesi belli API'ler
Siteniz, uygulamanız ve iş ortaklarınız için API tasarlıyor ve geliştiriyoruz; sözleşmeyi koddan önce yazıyor, sürümlüyor ve test ediyoruz.
Kimin için
Verisini ya da işlemlerini uygulamalara, iş ortaklarına veya başka sistemlere açması gereken şirketler için.
Neyi çözer
- Her iş ortağına farklı bir entegrasyon yapıldı; hepsini ayakta tutmak başlı başına iş oldu.
- API'deki bir değişiklik, entegre olmuş birinin uygulamasını bozdu.
- Belgeler güncel değil; belgede olması gereken cevapları destek ekibi tek tek veriyor.
- Hatalar genel mesajlarla dönüyor; iş ortağı neyi düzeltmesi gerektiğini anlamıyor.
Ne yapıyoruz
- Koddan önce sözleşme
- API, geliştirmeden önce OpenAPI ile tanımlanır ve onu kullanacak taraflarca gözden geçirilir.
- Kaynaklar ve hatalar
- Adlandırma, sayfalama, filtreler; neyin ters gittiğini ve nasıl düzeltileceğini söyleyen hata mesajları.
- Kimseyi bozmayan sürümler
- Sürüm politikası ve kullanımdaki bir özellik kaldırılmadan önce haber verme süresi.
- Kimlik doğrulama ve yetkiler
- Kimin neyi çağırabileceği: API anahtarları, OAuth ve iş ortağına göre kapsamlar.
- Kullanım sınırları
- Bir iş ortağı API'yi ötekiler için çökertmesin diye müşteri başına sınırlar.
- Test ortamı
- İş ortaklarının canlıya çıkmadan önce deneme yapacağı, sahte verili bir sandbox.
- Sözleşme testleri
- Bir değişiklik anlaşılanı bozduğunda uyaran otomatik testler.
Neler teslim edilir
- Depoda sürümlenen OpenAPI tanımı
- Kimlik doğrulaması, kullanım sınırları ve kayıtlarıyla canlıda çalışan API
- Başvuru belgeleri ve iş ortakları için başlangıç kılavuzu
- Entegrasyon testleri için sahte verili sandbox
- Her değişiklikte koşan otomatik sözleşme testleri
Nasıl ilerliyoruz
Kim kullanacak
API'yi kimin, ne için ve hangi hacimde kullanacağı.
Sözleşme
Ekibinizle ve varsa bir iş ortağıyla birlikte gözden geçirilen yazılı tanım.
Geliştirme
Sözleşmeye bağlı kalan, her cevabı testle doğrulayan uygulama.
Sandbox ve belgeler
Test ortamı ve kılavuzlar canlıdan önce yayımlanır.
Canlıya çıkış
Hataların ve müşteri başına kullanımın izlendiği yayın.
Teknoloji örnekleri
- OpenAPI
- GraphQL
- gRPC
- OAuth 2.0
- NestJS
- Spring Boot
- Pact
İlgili hizmetler
Sık sorulan sorular
REST mi, GraphQL mi, gRPC mi?
API'yi kimin kullanacağına bağlı. Dış iş ortakları için OpenAPI'li REST genellikle benimsemesi en kolay olanıdır. GraphQL ve gRPC, durum gerektirdiğinde devreye girer.
Uygulamayı ya da siteyi de siz mi yaparsınız?
Hayır. Biz API'yi yaparız; sözleşmeyi ön yüz ya da uygulama ekibinizle birlikte belirleriz. Ayrıntısı uygulama ve ön yüz için back-end sayfasında.
Var olan bir API'yi belgeleyebilir misiniz?
Evet. Mevcut API'yi OpenAPI ile tanımlar, tutarsızlıkları gösterir ve kullananları bozmayan yeni bir sürüm öneririz.
İş ortakları bir değişikliği nasıl öğrenir?
Sürüm politikasıyla: değişiklik yeni bir sürümle gelir, eski sürüm anlaşılan süre boyunca çalışmaya devam eder ve iş ortaklarına önceden haber verilir.
Balkan'a yazın
Projeniz için yazın