This document explains the installation of the Apinizer API Developer Portal.

1) Introduction

The API Developer Portal is the end-user or developer portal where API Consumers can access documentation related to APIs offered by an organization, test them, utilize them within specific constraints, and ask questions about them.

Similar to other Apinizer products, the API Developer Portal operates on the Kubernetes Platform. No database is used for portal operations; instead, interaction is facilitated directly through APIs provided by the API Manager.

2) Pre-installation Steps

Before starting the installation of the Apinizer API Portal, the following points should be noted:

  • API Manager must be installed. Please refer to the Apinizer Installation and Configuration documentation for API Manager Installation. 
  • Your license key must include the API Developer Portal component.

3) Installation Steps

The installation of the API Portal can be done in two ways:

  • If Kubernetes management is done through Apinizer, you can install the API Developer Portal via the API Manager.
  • If Kubernetes management is not done through Apinizer, manual installation can be performed on Kubernetes, followed by establishing a connection with the API Manager.

3.1) Installation of API Developer Portal via API Manager

For the installation of the API Developer Portal via API Manager, the following section in the General Settings menu must be active.


Once ensuring that Kubernetes management is conducted through Apinizer, you can proceed with the installation of the API Developer Portal by following the steps below:

Navigate to Management → Server Management → Kubernetes Resources page in the API Manager. Activate the API Portal from the Deployment & Pods tab. Complete the installation by making necessary configurations.


In the opened dialog, define the mandatory fields according to your organization's requirements.


FieldDescription
Apinizer Portal Management API URLThe address of the Management API run by the API Manager, necessary for the API Developer Portal to consume Apinizer Management APIs. Example address: http://apimanager-ui-ip-address:port/apiportal/management
Apinizer Portal Management API Key/Token

The token information required for the API Developer Portal to consume Apinizer Management APIs. Token information can be obtained by creating a new token or using an existing one in the Profile → page. Personnel tokens typically start with apnz_.

CountEquivalent to the number of gateway engines, similar to replicaSets in Kubernetes Cluster.
CPUThe maximum number of CPU cores that the Pod can use.
MemoryThe maximum memory value that the Pod can use.
Memory UnitThe unit of measurement for memory; MB, GB.
Additional VariablesDefault and optional variables and their values to be defined for running within the Pod. Default variables cannot be deleted, only their values can be edited.
Host AliasesIP addresses in the network can sometimes be appended with hostnames. If these are not defined in the nameserver or host file, or if Apinizer cannot resolve them in some way, Host Alias definitions should be made for worker pods to resolve these names.

When configuring the Java Options in the Additional Variables field, please consider the following warning:

Note that the -Xmx and -Xms settings disable automatic heap sizing.

Keep in mind that Apinizer configures JVM Heap values to utilize 75% of the allocated container memory since it runs within a container.

UseContainerSupport is enabled by default.

The old flags -XX:{Min|Max} RAMFraction have been deprecated. There is a new flag -XX:MaxRAMPercentage, which takes a value between 0.0 and 100.0 (defaulting to 25.0). If there is a 1 GB memory limit, the JVM heap is limited to approximately ~250 MB by default.

For more detailed information, click here.


Once the above steps are completed and the Pods belonging to the API Portal are ready on Kubernetes, access to the Portal Interface is provided via the following address.

http://<KUBERNETES_WORKER_IP>:<API_PORTAL_PORT>
POWERSHELL

3.2) Manual API Developer Portal Installation

For the manual installation of the API Developer Portal, the following steps should be followed:

Important: Create a Kubernetes Secret containing the API Manager API address and API Key/Token information. Fill in the following details according to your organization.

  • apinizerManagementApiBaseUrl: The address of the Management API running on API Manager, required for the API Developer Portal to consume Apinizer Management APIs. An example address would be: http://apimanager-ui-ip-address:port
  • apiKey: The token information required for the API Developer Portal to consume Apinizer Management APIs. You can create a new token on the "My Profile" page or use an existing one.  

    Personal tokens start with apnz_.

API_MANAGER_URL='<APINIZER_MANAGEMENT_API_BASE_URL>'

API_MANAGER_APIKEY='<API_KEY>'

echo -n ${API_MANAGER_URL} | base64
//Bunun çıktısını bir sonraki adımda <ENCODED_URL> değişkeni yerine koyacağız
 
echo -n ${API_MANAGER_APIKEY} | base64
//Bunun çıktısını bir sonraki adımda <ENCODED_API_KEY> değişkeni yerine koyacağız
POWERSHELL 

vi api-portal-secret.yaml
POWERSHELL 

apiVersion: v1
kind: Namespace
metadata:
  name: apinizer-portal

---
apiVersion: v1
kind: Secret
metadata:
 name: apinizer-portal-secret
 namespace: apinizer-portal
type: Opaque
data:
  apinizerManagementApiBaseUrl: <ENCODED_URL>
  apiKey: <ENCODED_API_KEY>
YML 
kubectl apply -f api-portal-secret.yaml
POWERSHELL 
vi apinizer-portal-deployment.yaml
POWERSHELL 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apinizer-portal
  namespace: apinizer-portal
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apinizer-portal
      version: v1
  template:
    metadata:
      labels:
        app: apinizer-portal
        version: v1
    spec:
      containers:
        - name: apinizer-portal-app
          image: apinizercloud/portal:<APINIZER_VERSION>
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: prod
            - name: JAVA_OPTS
              value: ' -Xmx1400m -Xms1400m'
            - name: API_PORTAL_MANAGEMENT_API_BASE_URL
              valueFrom:
                secretKeyRef:
                  key: apinizerManagementApiBaseUrl
                  name: apinizer-portal-secret
            - name: API_PORTAL_MANAGEMENT_API_KEY
              valueFrom:
                secretKeyRef:
                  key: apiKey
                  name: apinizer-portal-secret
          resources:
            limits:
              memory: 2Gi
              cpu: 1
          ports:
            - name: http
              containerPort: 8080

---
apiVersion: v1
kind: Service
metadata:
  name: apinizer-portal-service
  namespace: apinizer-portal
  labels:
    app: apinizer-portal
spec:
  selector:
    app: apinizer-portal
  type: NodePort
  ports:
    - name: http
      port: 8080
      nodePort: <API_PORTAL_PORT>
YML 
kubectl apply -f apinizer-portal-deployment.yaml
POWERSHELL


Important

Up to this point, the API Developer Portal interface installation may have been completed. However, integration with API Manager is required for APIs to be viewable on the API Developer Portal, for credential creation, and for other functionalities to be utilized.

3.3) Integration of the API Developer Portal with API Manager

In API Manager, go to Management → Portal Management → Settings page, and make the appropriate definitions for your organization.

Firstly, you need to define your API Developer Portal address.

FieldDescription
Custom Portal URLThe access address of the API Portal interface is entered. Example: https://apiportal.company.com
Auto Approve Account/DevelopersWhen this feature is enabled, accounts/developers registering through the API Portal can directly access the API Portal without requiring approval from the Portal Manager.
Allow Organization Administrator to Manage their own AccountsWhen this feature is enabled, it determines whether Organization Managers have the authority to manage their own accounts when creating new registrations via the Account/Developer menu. This setting allows the account/developer to create their own account on the API Portal.
Define Your EMail Server for Sending Email to UsersDefines the selection of the necessary email server for sending emails to users from the API Portal.
Define your API Performance MetricsConfigurations for the following fields are made in this section:
Maximum Acceptable Value For Good Performance: The maximum value that indicates normal response time for a request is entered.
Minimum Acceptable Value For Bad Performance: The minimum value that indicates abnormal response time for a request is entered.
Define your API Portal Legal AgreementManages the text containing the terms and conditions that users need to agree to when registering for the API Portal.

3.4) Starting the API Developer Portal with SSL

Firstly, upload your certificate file with a .p12 extension to Kubernetes as a secret.

kubectl create secret generic apinizer-portal-tls --from-file=portal.p12 -n apinizer-portal
POWERSHELL

Creating PKCS12 from JKS

keytool -genkeypair -alias portal -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore portal.p12 -validity 3650 -storepass password


Variables to be defined:

VariableDescription
SSL_KEY_STOREThe path to the key store that contains the SSL certificate. In our example, we want Spring Boot to search for this in the classpath.
SSL_KEY_STORE_PASSWORDThe password used to access the key store.
SSL_KEY_STORE_TYPEThe type of the key store (Use: PKCS12).
SSL_KEY_ALIASThe alias that identifies the key in the key store.
SSL_ENABLEDEnables the usage of HTTPS protocol for the Spring Boot application.
SERVER_PORTThe port on which the server is listening. We have used 8443 rather than the default 8080 port.


A sample YAML file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: apinizer-portal
  namespace: apinizer-portal
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apinizer-portal
      version: v1
  template:
    metadata:
      labels:
        app: apinizer-portal
        version: v1
    spec:
      volumes:
      - name: apinizer-portal-tls
        secret: 
          secretName: apinizer-portal-tls
      containers:
      - name: apinizer-portal
        image: apinizerqa/portal:2024.01.5.qa.2
        imagePullPolicy: IfNotPresent
        resources:
          limits:
            cpu: 1
            memory: 2Gi
        lifecycle:
          preStop:
            exec:
              command:
              - /bin/sh
              - -c
              - sleep 10
        ports:
        - containerPort: 8443
          protocol: TCP
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: prod
        - name: JAVA_OPTS
          value: "-Xmx1400m -Xms1400m"
        - name: SSL_KEY_STORE
          value: /etc/ssl/certs/portaljksli.p12
        - name: SSL_KEY_STORE_PASSWORD
          value: password
        - name: SSL_KEY_STORE_TYPE
          value: PKCS12
        - name: SSL_KEY_ALIAS
          value: portal
        - name: SSL_ENABLED
          value: "true"
        - name: SERVER_PORT
          value: "8443"
        - name: API_PORTAL_MANAGEMENT_API_BASE_URL
          valueFrom:
            secretKeyRef:
              key: apinizerManagementApiBaseUrl
              name: apinizer-portal-secret
        - name: API_PORTAL_MANAGEMENT_API_KEY
          valueFrom:
            secretKeyRef:
              key: apiKey
              name: apinizer-portal-secret
        volumeMounts:
        - name: apinizer-portal-tls
          mountPath: /etc/ssl/certs
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

---
apiVersion: v1
kind: Service
metadata:
  name: apinizer-portal-https-service
  namespace: apinizer-portal
  labels:
    app: apinizer-portal
spec:
  selector:
    app: apinizer-portal
  type: NodePort
  ports:
    - name: http
      port: 8443
      nodePort: 30843
POWERSHELL