OpenAPI

HTTP API sözleşmesini anlaşılır biçimde kaydetmek

OpenAPI, HTTP API’lerini tanımlamak için bir standarttır. Bir OpenAPI tanımı, sunulan yolları, işlemleri, parametreleri ve yanıt yapılarını kaydeder. JSON veya YAML biçiminde gösterilebilir. Tanımlama dili, servisin hangi programlama diliyle geliştirildiğine bağlı değildir.

Kurgusal bir yazılım şirketi, proje portalı için GET /projects/{projectId} planlar. Tanımda projectId bir yol parametresi olarak belirtilecek; başarılı 200 yanıtında diğer alanlarla birlikte metin türünde name alanı bulunacaktır. Bilinen hata yanıtları da sözleşmeye dahildir. Yol ve alanlar bize ait tasarım örnekleridir; eksiksiz OpenAPI belgesi veya mevcut servis değildir.

Ön yüz ekibi hangi bilgileri göndermesi, hangi yanıtları işlemesi gerektiğini buradan anlayabilir. Ancak dosya tek başına çalışan uygulamanın sözleşmeye uyduğunu göstermez. Teslim öncesinde tanım ile gerçek yanıtlar, hata durumları dahil karşılaştırılmalıdır. name alanının anlamı da kararlaştırılmalıdır: Metin türünün doğru olması, alanın hangi adı taşıdığını açıklamaz.

Kaynaklar

• OpenAPI Initiative · OpenAPI Specification