Azure API Developer Portal’ın Self-Host Yapılandırılması

API Developer Portal çözümleri, API sağlayıcı kuruluşların API tüketicileri için sunmuş oldukları API’leri ve bu API’lerin dokümantasyonlarını yayınladıkları uygulamalardır. Developer portal ile API tüketicileri, API sağlayıcı bir kuruluşun hangi API’leri sunduğunu, bu API’lerin nasıl kullanıldığını görüntüleyebilmekte ve API ürünleri için abonelik işlemlerini yönetebilmektedir.

Bu içerikte Microsoft’un açık kaynak olarak yayınladığı Azure API Management Developer Portal uygulamasının self-host olarak yapılandırılmasını inceliyor olacağız.

1. Config Dosyalarının Yapılandırılması

Öncelikle github’dan api-management-developer-portal repo’sunu local’imize çekiyoruz.

git clone https://github.com/Azure/api-management-developer-portal.git

Portal için bilgisayarımızda Node.js’in v10.15.0 veya üzeri bir versiyonunun kurulu olması gerekmektedir.

node --version

Eğer Node.js versiyonu v10.15.0 veya üzeri ise NPM paketlerinin kurulumuna geçebiliriz.

npm install

Yapılandırma ve build işlemleri öncesinde Azure Portal’den API Management Service örneği yaratmamız gerekmektedir. Eğer henüz API management service örneğine sahip değilseniz “Create a new Azure API Management service instance” içeriğini inceleyebilirsiniz.

Projemizin src dizininde yapılandırılması gereken 3 adet config dosyası bulunmakta.

-- src
--- config.design.json
--- config.publish.json
--- config.runtime.json

Config dosyaları için gerekli olan bilgileri Azure Portal’den oluşturduğumuz API Management Service örneğinden almaktayız.

Config dosyalarında yer alan Management API Url ve Backend Url bilgilerini Overview panelinden alabiliriz.

Access Token bilgisini ise Managament API panelinden generate etmekteyiz. Üretmiş olduğumuz token’ın geçerlilik süresi en fazla 30 gün olabilir. Token bilgisine uygulamayı publish ederken ve önyüz düzenlemelerini yaparken ihtiyaç duymaktayız, güvenlik nedeniyle token ömrünü kısa tutmakta fayda var.

Config dosyalarına url ve token bilgilerini girdikten sonra projemizi designer modda ayağa kaldırıp önyüz düzenlemelerini yapmaya başlayabiliriz.
config.design.json

{
    "environment": "development",
    "managementApiUrl": "https://hello-api-management.management.azure-api.net",
    "managementApiAccessToken": "SharedAccessSignature integration&202210071920&CwB+CV6tOC2kmZBqMMrfYIEKSAtRrMJjTb0Sw==",    
    "backendUrl": "https://hello-api-management.developer.azure-api.net",
    "useHipCaptcha": false
}

config.publish.json

{
    "environment": "publishing",
    "managementApiUrl": "https://hello-api-management.management.azure-api.net",
    "managementApiAccessToken": "SharedAccessSignature integration&202210071920&CwB+CV6tOC2kmZBqMMrfYIEKSAtRrMJjTb0Sw==",
    "useHipCaptcha": false
}

config.runtime.json

{
    "environment": "runtime",
    "managementApiUrl": "https://hello-api-management.management.azure-api.net",
    "backendUrl": "https://hello-api-management.developer.azure-api.net"
}

2. Önyüz Düzenlemeleri ve Custom Widget

Azure Developer Portal uygulamasını designer modda ayağa kaldırıp, tek satır kod yazmadan mevcut widget ve template’leri kullanarak; yeni sayfalar oluşturabilir, mevcut sayfaların önyüzünde değişiklikler yapabilir, çözünürlüğe göre sayfa tasarımlarını farklılaştırabilir, ziyaretçi ve üye ayrımına göre sayfa düzenini değiştirebiliriz.

npm start

Eğer sunulan mevcut widget ve template’ler ihtiyacımızı karşılıyorsa self-host yerine uygulamayı direkt azure’da servis olarak kullanmayı tercih edebiliriz. Ancak projede kod değişikliği gerekiyorsa uygulamayı kendi sunucularımızda barındırmamız gerekmektedir.

İhtiyaçlarımız doğrultusunda kendi widget ve componentlerimizi geliştirebilmemiz için temel düzeyde Knockout, TypeScipt, Html ve CSS bilmemiz yeterli olacaktır.

FAQ sayfasında kullanmak üzere geliştirmiş olduğum collapsible widgetının kaynak kodlarını github hesabımdan inceleyebilirsiniz.

3. Build ve Environment Yönetimi

Geliştirmeler tamamlandıktan sonra Webpack ile build ve publish işlemlerini gerçekleştirebiliriz.

npm run publish

Publish işleminden sonra projemizin ana dizininde dist isimli bir klasör oluşacaktır. Bu klasör içerisinde yer alan website klasörü uygulamamızın build edilmiş, yayınlanabilir dosyalarını içermektedir. Developer portal’i yayına almak için website altındaki dosyaları FTP ile sunucularımıza aktarabiliriz veya tüm bu işlemleri manuel yapmak yerine Jenkins ile build, publish ve deployment işlemlerini otomatize edebiliriz.

Genellikle uygulamalarımızı PROD haricinde DEV, UAT, PREPROD gibi farklı ortamlarda da yayınlarız. Ortam bazlı olarak değişecek değerleri projemiz build olduktan sonra oluşan dist/website dizini içerisindeki config.json dosyasında tutabiliriz. config.json dosyası src/config.runtime.json dosyasından oluşturulduğu için değişkenleri build öncesinde de atayabiliriz. Bu değişkenlere geliştirmekte olduğumuz componentlerden erişmek için settingsProvider sınıfını kullanmaktayız.

import { ISettingsProvider } from "@paperbits/common/configuration";
...
   const settings = await this.settingsProvider.getSettings();
   const managementApiUrl = settings["managementApiUrl"];

Okunabilirliği zorlaştırmamak için bu içerikte config dosyalarının yapılandırılması, projenin ayağa kaldırılması ve önyüz düzenlemeleri gibi temel başlıklara yer vermeye çalıştım. Farklı bir içerikte Azure API Management servis örneğini biraz daha yakından inceleyerek authentication, notifications başlıklarına da yer vermeye çalışacağım.