Management API

Introduction

This guide will walk through how to configure your general DSAPI APIM Management API settings using the DSAPI.yaml file. As detailed in the Configuring APIM Components, you can override these settings by using system properties or environment variables.

The DSAPI.yaml file, found in DSAPI_HOME/config/, is the default way to configure APIM.

With the DSAPI.yaml file, you can configure the following:

• HTTP Server
• Management and Portal APIs
• CORS
• Management repository
• Analytics repository
• SMTP
• Default DSAPI.yaml file

Configure HTTP server

You configure the HTTP Server configuration in the following section of the DSAPI.yml file:

jetty:
  port: 8083
  idleTimeout: 30000
  acceptors: -1
  selectors: -1
  pool:
    minThreads: 10
    maxThreads: 200
    idleTimeout: 60000
    queueSize: 6000
  jmx: false
  statistics: false
  accesslog:
    enabled: true
    path: ${DSAPI.home}/logs/DSAPI_accesslog_yyyy_mm_dd.log

Enable HTTPS support

First, you need to provide a keystore. If you do not have one, you can generate it:

keytool -genkey \
  -alias test \
  -keyalg RSA \
  -keystore server-keystore.jks \
  -keysize 2048 \
  -validity 360 \
  -dname CN=localhost \
  -keypass secret \
  -storepass secret

You then need to enable secure mode in DSAPI.yml:

jetty:
  ...
  secured: true
  ssl:
    keystore:
      path: ${DSAPI.home}/security/keystore.jks
      password: secret
    truststore:
      path: ${DSAPI.home}/security/truststore.jks
      password: secret

Configure the Management and Portal APIs

You can configure APIM API to start only the Management or Portal API. You can also change the API endpoints from their default values of /management and /portal.

http:
  api:
    # Configure the listening path for the API. Default to /
#    entrypoint: /
    # Configure Management API.
#    management:
#      enabled: true
#      entrypoint: ${http.api.entrypoint}management
#      cors: ...
    # Configure Portal API.
#    portal:
#      enabled: true
#      entrypoint: ${http.api.entrypoint}portal
#      cors: ...

CORS configuration

CORS (Cross-Origin Resource Sharing) is a mechanism that allows resources on a web page to be requested from another domain.

For more information on CORS, take a look at the CORS specification.

CORS can be applied at three different levels:

1. API
2. Environment
3. Organization

where the more specific levels override the broader levels: API > Environment > Organization.

You can configure CORS at the organization level using DSAPI.yml, environment variables or directly in APIM Console. Here's an example of configuring CORS using the DSAPI.yml file:

http:
  api:
    # Configure the listening path for the API. Default to /
#    entrypoint: /
    # Configure Management API.
#    management:
#      enabled: true
#      entrypoint: ${http.api.entrypoint}management
#      cors:
    # Allows to configure the header Access-Control-Allow-Origin (default value: *)
    # '*' is a valid value but is considered as a security risk as it will be opened to cross origin requests from anywhere.
#       allow-origin: http://developer.mycompany.com
    # Allows to define how long the result of the preflight request should be cached for (default value; 1728000 [20 days])
#       max-age: 864000
    # Which methods to allow (default value: OPTIONS, GET, POST, PUT, DELETE)
#      allow-methods: 'OPTIONS, GET, POST, PUT, DELETE'
    # Which headers to allow (default values: Cache-Control, Pragma, Origin, Authorization, Content-Type, X-Requested-With, If-Match, X-Xsrf-Token)
#      allow-headers: 'X-Requested-With'
  # Configure Portal API.
#    portal:
#      enabled: true
#      entrypoint: ${http.api.entrypoint}portal
#      cors:
    # Allows to configure the header Access-Control-Allow-Origin (default value: *)
    # '*' is a valid value but is considered as a security risk as it will be opened to cross origin requests from anywhere.
#       allow-origin: http://developer.mycompany.com
    # Allows to define how long the result of the preflight request should be cached for (default value; 1728000 [20 days])
#       max-age: 864000
    # Which methods to allow (default value: OPTIONS, GET, POST, PUT, DELETE)
#      allow-methods: 'OPTIONS, GET, POST, PUT, DELETE'
    # Which headers to allow (default values: Cache-Control, Pragma, Origin, Authorization, Content-Type, X-Requested-With, If-Match, X-Xsrf-Token)
#      allow-headers: 'X-Requested-With'

Configure in APIM Console

You can also configure CORS at the organization level in the Organization > Settings section of the APIM Console:

Or at the environment level in the Settings > Settings section of the APIM Console:

Configure the Management repository

The Management repository is used to store global configurations such as APIs, applications, and API keys. The default configuration uses MongoDB (single server).

management:
  type: mongodb
  mongodb:
    dbname: ${ds.mongodb.dbname}
    host: ${ds.mongodb.host}
    port: ${ds.mongodb.port}
#    username:
#    password:
#    connectionsPerHost: 0
#    connectTimeout: 500
#    maxWaitTime: 120000
#    socketTimeout: 500
#    socketKeepAlive: false
#    maxConnectionLifeTime: 0
#    maxConnectionIdleTime: 0
#    serverSelectionTimeout: 0
#    description: DSAPI.io
#    heartbeatFrequency: 10000
#    minHeartbeatFrequency: 500
#    heartbeatConnectTimeout: 1000
#    heartbeatSocketTimeout: 20000
#    localThreshold: 15
#    minConnectionsPerHost: 0
#    threadsAllowedToBlockForConnectionMultiplier: 5
#    cursorFinalizerEnabled: true
## SSL settings (Available in APIM 3.10.14+, 3.15.8+, 3.16.4+, 3.17.2+, 3.18+)
#    sslEnabled:
#    keystore:
#      path:
#      type:
#      password:
#      keyPassword:
#    truststore:
#      path:
#      type:
#      password:
## Deprecated SSL settings that will be removed in 3.19.0
#    sslEnabled:
#    keystore:
#    keystorePassword:
#    keyPassword:

# Management repository: single MongoDB using URI
# For more information about MongoDB configuration using URI, please have a look to:
# - http://api.mongodb.org/java/current/com/mongodb/MongoClientURI.html
#management:
#  type: mongodb
#  mongodb:
#    uri: mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

# Management repository: clustered MongoDB
#management:
#  type: mongodb
#  mongodb:
#    servers:
#      - host: mongo1
#        port: 27017
#      - host: mongo2
#        port: 27017
#    dbname: ${ds.mongodb.dbname}
#    connectTimeout: 500
#    socketTimeout: 250

Configure the Analytics repository

The Analytics repository stores all reporting, metrics, and health-checks for all APIM Gateway instances. The default configuration uses Elasticsearch.

  type: elasticsearch
  elasticsearch:
    endpoints:
      - http://localhost:9200
#    index: DSAPI
#    security:
#       username:
#       password:

SMTP configuration

This section shows the SMTP configuration used for sending email.

You can configure SMTP using DSAPI.yml, environment variables or directly in APIM Console. If SMTP is configured with DSAPI.yml or environment variables, then that configuration will be used, even if settings exist in the database.

SMTP can be applied at two different levels:

1. Environment
2. Organization

where the more specific level overrides the broader level: Environment > Organization.

Here's an example of configuring SMTP using the DSAPI.yml file:

email:
  host: smtp.my.domain
  port: 465
  from: noreply@my.domain
  subject: "[DSAPI.io] %s"
  username: user@my.domain
  password: password

Configure in APIM Console

You can also configure SMTP at the organization level in the Organization > Settings section of the APIM Console:

Or at the environment level in the Settings > Settings section of the APIM Console:

Configure the Gmail SMTP server

If required, you can configure the GMAIL SMTP server in DSAPI.yml as follows:

email:
  enabled: true
  host: smtp.gmail.com
  port: 587
  from: user@gmail.com
  subject: "[DSAPI.io] %s"
  username: user@gmail.com
  password: xxxxxxxx
  properties:
    auth: true
    starttls.enable: true
    ssl.trust: smtp.gmail.com

If you are using 2-Factor Authentication (which is recommended), you need to generate an application password.

User and Management Configuration

Introduction

The following sections discuss user and management configuration.

User configuration

You can configure various user options:

• user.login.defaultApplication: boolean (default: true): Creates a new application for all new users
• user.creation.token.expire-after: number (default: 86400): Number of seconds before the user registration token expires
• user.reference.secret: 32 characters (default: s3cR3t4grAv1t33.1Ous3D4R3f3r3nc3): Secret used to generate a unique anonymous reference to a user; You must change this value
• user.anonymize-on-delete:enabled: boolean (default: false): If true, the user's first name, last name, and email are anonymized when a user is deleted

Management configuration

You can configure various management settings in the APIM Console Settings page with environment variables. For a complete list of these settings. Once you override these properties with environment variables, APIM Console configures them as read-only to prevent you from overwriting the new values in the interface.

For example, you can override the analytics client timeout with either of the following environment variables:

DSAPI_analytics_client_timeout=15000
DSAPI.analytics.client.timeout=15000

Security

Brute-force attacks

A brute-force attack is the submission of a high volume of authentication requests consisting of password permutations. Even with OAuth 2.0 enabled, you can leave behind a login form for in-memory or local users. Some tools can help you to prevent malicious actions by banning IPs.

Fail2Ban

This section explains how to secure the APIM UI components (Management and Portal) and APIM APIs against brute-force attacks using Fail2Ban. For instructions on installing Fail2Ban, see the Fail2Ban website.

Configuration

APIM API logs all authentication failures in the DSAPI log file. Follow the steps below to configure Fail2Ban to work with the DSAPI log file.

1. Configure a Fail2Ban filter to extract DSAPI authentication failure events:

   2019-05-03 16:03:03.304 [DSAPI-listener-31] WARN  i.g.m.s.l.AuthenticationFailureListener - Authentication failed event for : admin - IP : 10.50.24.18
   

2. Add a configuration file to declare filters: /etc/fail2ban/filter.d/DSAPI.conf.

   [Definition]
   failregex = .*Authentication failed event for.*IP : <HOST>
   ignoreregex =
   

3. Add Fail2Ban actions to DSAPI.conf. Actions are iptables or firewalld commands.

   [INCLUDES]
   
   before = iptables-common.conf
   
   [Definition]
   
   # Option:  actionstart
   # Notes.:  command executed once at the start of Fail2Ban.
   # Values:  CMD
   #
   actionstart = <iptables> -N f2b-<name>
                 <iptables> -A f2b-<name> -j <returntype>
                 <iptables> -I <chain> -p <protocol> --dport <port> -j f2b-<name>
   
   # Option:  actionstop
   # Notes.:  command executed once at the end of Fail2Ban
   # Values:  CMD
   #
   actionstop = <iptables> -D <chain> -p <protocol> --dport <port> -j f2b-<name>
                <iptables> -F f2b-<name>
                <iptables> -X f2b-<name>
   
   # Option:  actioncheck
   # Notes.:  command executed once before each actionban command
   # Values:  CMD
   #
   actioncheck = <iptables> -n -L <chain> | grep -q 'f2b-<name>[ \t]'
   
   # Option:  actionban
   # Notes.:  command executed when banning an IP. Take care that the
   #          command is executed with Fail2Ban user rights.
   # Tags:    See jail.conf(5) man page
   # Values:  CMD
   #
   actionban = <iptables> -I f2b-<name> 1 -p tcp -m string --algo bm --string 'X-Forwarded-For: <ip>' -j DROP
   
   # Option:  actionunban
   # Notes.:  command executed when unbanning an IP. Take care that the
   #          command is executed with Fail2Ban user rights.
   # Tags:    See jail.conf(5) man page
   # Values:  CMD
   #
   actionunban = <iptables> -D f2b-<name> -p tcp -m string --algo bm --string 'X-Forwarded-For: <ip>' -j DROP
   
   [Init]
   

4. Declare the new DSAPI Fail2Ban block in the main configuration file with the required parameters:

   [DSAPI]
   banaction = DSAPI
   logpath = /opt/DSAPI-io-management-api/logs/management_api.log
   filter = DSAPI
   enabled = true
   maxretry = 3
   

Configuring the Internal API

Overview

The DSAPI API Management (APIM) Management API component includes its own internal API for monitoring and retrieving technical information about the component.

Configuration

Enable the API as a service in the DSAPI.yml file and update any other required configuration:

services:
  core:
    http:
      enabled: true
      port: 18083
      host: localhost
      authentication:
        type: basic
        users:
          admin: adminadmin

The above values are defined as follows:

• enabled: Whether the service is enabled (default true).
• port: The port the service listens on (default 18083). Ensure you use a port not already in use by another APIM component.
• host: The host (default localhost).
• authentication.type: Authentication type for requests (default basic). Use the value none if no authentication is required.
• authentication.users: A list of user: password combinations. Only required if authentication type is basic.

Endpoints

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "a70b9fd9-9deb-4ccd-8b9f-d99deb6ccd32",
    "metadata": {},
    "name": "DSAPI.io - Management API",
    "version": {
        "BUILD_ID": "309",
        "BUILD_NUMBER": "309",
        "MAJOR_VERSION": "1.20.14",
        "REVISION": "132e719ef314b40f352e6399034d68a9a95e95ef"
    }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
"management-api": {
"healthy": true
},
"management-repository": {
"healthy": true
},
"api-sync": {
"healthy": true
},
"api-sync": {
"healthy": true
}
}

HTTP/1.1 200 OK
Content-Type: application/json
{
"analytics.elasticsearch.endpoints[0]": "http://${ds.elastic.host}:${ds.elastic.port}",
"analytics.type": "elasticsearch",
"ds.elastic.host": "localhost",
"ds.elastic.port": 9200,
...
}

HTTP/1.1 200 OK
Content-Type: application/json
{
"jvm": {
"gc": {
"collectors": [
{
"collectionCount": 7,
"collectionTime": 98,
"name": "young"
},
{
"collectionCount": 3,
"collectionTime": 189,
"name": "old"
}
]
},
"mem": {
...
}

Developer Portal

Overview

The Developer Portal is a web application that provides a simplified, user-friendly interface tailored to the API consumption process. It acts as a centralized catalog where internal and external API consumers can find and subscribe to APIs that are developed, managed, and deployed by API publishers.

API consumers can easily discover and explore APIs, read documentation, test API endpoints, generate access tokens, view API analytics, and manage their API subscriptions in a single location. Additionally, administrators have significant control over the look and feel of the Developer Portal to deliver an accessible and on-brand experience to external API consumers.

For more information about the DSAPI Developer Portal, see the following the articles:

Accessing the DSAPI Developer Portal

Users should be able to immediately access the Developer Portal from the APIM Console by selecting the Developer Portal link in the top left of the Console's nav bar.

Self-managed installation: Adding a Developer Portal link

The Developer Portal host of self-managed installations can easily be modified. You can manually add the Portal URL to see the Developer Portal link in the Console UI.

Your Developer Portal URL will depend on your deployment, so please reference the respective installation docs. For example, with the default Docker installation, you can access the Developer Portal at http://localhost:8085 in your browser.

• Click Settings in the sidebar
• Click Settings in the inner sidebar
• Scroll down to Portal settings and provide a Portal URL based on your deployment configuration
• Scroll to the bottom of the page and click Save

• Select the Developer Portal link in the top left of your Console's nav bar

This will bring you to the homescreen of the Developer Portal.

From here, you can immediately begin searching for APIs using the Developer Portal's full-context[^1] search. However, you will not be able to subscribe to any APIs until you create an application.

[^1]: Full-context meaning it searches through the definition and metadata of all published APIs that you have access to

Creating and managing users with the DSAPI Developer Portal

Overview

When you access the Developer Portal directly from the Management Console, you are automatically signed in with the same account. However, to expose your APIs to consumers you will need to create new accounts, which requires additional configuration.

User sign-up

To create new user accounts you must:

• Enable the Allow User Registration option. This option is a general setting and enabled by default.
• Configure simple mail transfer protocol (SMTP) to confirm user account creation. See the sections below for detailed instructions.

Configure SMTP

To configure SMTP settings:

1. Log in to the Management Console
2. Select Settings from the left sidebar
3. Select Settings from the inner left sidebar
4. Configure the SMTP settings are at the bottom of the page

Create a user

After configuring SMTP, you can create a new user in the Developer Portal:

1. Open the Developer Portal in an incognito window to avoid being automatically signed in with the same account used by the Management Console
2. In the new incognito window, select Sign up at the bottom of the modal
3. Provide the required information and click the Sign Up button

You will receive a registration confirmation at the email address you provided.

Complete sign-up

To complete the sign-up process:

1. Open the email and click the link
2. Ensure the link opens in the incognito tab (otherwise, the Developer Portal will use the same account as the Management Console)
3. Finalize your account and add a password that meets the following requirements:
   • 8 to 32 characters
   • No more than 2 consecutive identical characters
   • Minimum of 1 special character (@ & # …)
   • Minimum of 1 uppercase character

Once your password has been created, you will be able to sign in.

User overview

All users can be viewed in the Management Console by anyone with administrator privileges. To view users:

1. Select Organization at the bottom of the left sidebar
2. Select Users from the organization's left sidebar to display a list of all current users tied to the organization

As an administrator, you can click on an entry for user details and to apply administrative policies. Additionally, admins can pre-register users by clicking the Add user button on the top right of the page.

Webhook Subscription Management

Overview

API consumers can configure their Webhook subscriptions from the Developer Portal. Configuration involves adding a callback URL, choosing an application, and validating the request.

Configuration

Before you can define and configure your Webhook subscription, you'll need to find it in the Developer Portal:

1. Click on Catalog in the header

2. (Optional) Use the search field

   

3. Click on the subscription, then on Subscribe

   

4. Choose a PUSH plan. A PUSH plan is limited to Webhooks and enables you to subscribe to APIs that have a subscription listener (currently also limited to Webhooks).

   

5. Next, select your subscription channel and Webhook entrypoint, then define:

   • Callback URL
   • HTTP headers
   • Security config
   • Security type (basic, token, or OAuth2)
   • SSL options:
     • Enable or disable Verify Host
     • Enable or disable Trust all
     • Define your Trust store
     • Define your Key store

6. Next, choose which application will be the subscriber and (optionally) leave a message for the API Owner.

   

7. Select Next to validate your subscription request

   

Viewing API Documentation with DSAPI Developer Portal

Overview

The Developer Portal contains a Documentation section where API consumers can access information on published APIs.

View documentation

To find and view API documentation:

1. Click on Documentation in the Developer Portal header
2. Click on an entry in the left panel to view the documentation for that API

Configuring and customizing the DSAPI Developer Portal

You can configure and custmize the Developer Portal for your environment. For more information about configuring and customizing the Developer Portal, see the following articles:

Customizing the layout and theme of the DSAPI Developer Portal

Overview

Administrators have the option to modify the layout and theme of the Developer Portal to customize how APIs are presented to API consumers. The following sections describe which elements can be modified and provide instructions:

• API Sidebar
• API Catalog
• Custom navigation
• Theming

API Sidebar

You can click on an API in the Developer Portal to access its details. Selecting the General information header tab will display the API's description and reviews (if any have been submitted), as well as a sidebar on the right that contains additional information.

Administrators can control what is shown in the sidebar. To modify the access URL:

1. Select Organization at the bottom of the left sidebar of the Management Console
2. In the organization's left sidebar, select Sharding tags under the Gateway subheader
3. Modify the Default entrypoint of the DSAPI Gateway

The access URL for each API in the Developer Portal is the default entrypoint followed by that API's context path.

Sharding Tags and Gateway Entrypoint Mappings

Sharding Tags tags are used to help manage complex distributed architectures:

• By assigning sharding tags to APIs and DSAPI Gateways, an API is deployed to a subset of the available Gateways.
• By mapping sharding tags to a Gateway’s entrypoint URL, the Developer Portal can intelligently display different entrypoints based on an API's sharding tags.

To modify the sidebar settings:

1. Return to the Management Console's home page
2. Select Settings from the left sidebar
3. Select API Portal Information from the inner left sidebar to display the following options:

• Add extra information

  • Show tags list in the API header: Display all API labels in the Developer Portal
  • Show categories list in the API header: Display all API categories in the Developer Portal

• Configure the information list: Display custom values in the Developer Portal. Use the + icon on the bottom right of the page to add new values.

• API Page list options: Display a banner at the top of each page in the API Catalog to promote a particular API. The tab automatically determines which API to promote, e.g., the Starred tab will feature the API that was most recently reviewed.

  

API Catalog

Categories

Administrators can modify the browsing experience offered by the Developer Portal's API Catalog. To organize APIs by category:

• API categories must be added
• One or more categories must be applied to each API
• The Categories tab must be added to the API Catalog

To enable the Categories tab and modify categories:

1. Select Settings from the left sidebar of the Management Console
2. Select Categories from the inner left sidebar
   • Toggle Enable Category Mode to display the Categories tab
   • Create new categories and/or modify or delete existing categories

To apply categories:

1. Select APIs from the left sidebar of the Management Console
2. Select the API to which you want to add categories
3. Select Info from the inner left sidebar
4. Use the Categories dropdown to select one or more categories to apply to the API

With the toggle enabled, a Categories tab will appear in the header of the API Catalog:

Top/featured APIs

Administrators can also control what is displayed on the Featured page of the API Catalog by modifying the top APIs:

1. Select Settings from the left sidebar of the Management Console
2. Select Top APIs from the inner left sidebar

Administrators can use the + icon to add new APIs, reorder APIs, and remove APIs from the list. APIs added here are displayed on both the Developer Portal's homepage and on the API catalog's Featured page:

Custom navigation

Administrators can customize the header and footer navigation of the Developer Portal by creating link pages in DSAPI's system folders. There are three types of links:

• External link
• Link to an existing documentation page
• Link to a category

Each link is treated as a new documentation page. To learn about the features and functionality of Developer Portal documentation, see Documentation.

To access DSAPI's system folders:

1. Select Settings from the left sidebar of the Management Console
2. Select Documentation from the inner left sidebar

System folders are identified by a padlock icon:

There are three system folders: Header, TopFooter and Footer. Each system folder corresponds to an area of the Developer Portal:

TopFootersystem folder nesting

TheTopFootersystem folder is the only system folder that accepts nested folders, which are used to group links together. Nested folders must be published to be visible in the Developer Portal.

To create a link:

1. Open a system folder
2. Select the + icon
3. Select the Link icon

This will take you to a new page to select your link type and provide additional information about your link:

To view your new link, click Save and navigate to the Developer Portal:

Each custom link offers additional features such as translations and access control. See Documentation for more information.

Theming

Administrators can change the default theme of the Developer Portal to a custom theme. To modify the theme:

1. Select Settings from the left sidebar of the Management Console
2. Select Theme from the inner left sidebar

This page allows the administrator to customize every aspect of the Developer Portal's look and feel. Edits are shown in a live preview on the right.

The top menu includes the following options:

• Fullscreen: Opens the preview in a new window to avoid switching screens when editing.
• Reset: Resets the theme from the last backup. Backups occur when you select the Save button.
• Save: Saves your theme.
• Enabled: Activates the theme in APIM Portal.
• Import: Upload a custom theme in JSON format. To view the required structure of the JSON file, Export the current theme.
• Export: Downloads your current theme in JSON format.
• Restore Default Theme: Overwrites your modifications with the default theme.

Basic customization

Advanced customization

Each component uses its own properties but, where possible, the properties are grouped into common variables. To further customize the Developer Portal, you can define the graphic properties to expose for each component.

For example, hover your mouse over the color bubble to see common component colors. For other property types, if a common property is used, it appears in the placeholder field.

Override theme files

APIM API includes a default theme and two default logos, located in the /themes folder of the API distribution folder:

• definition.json
• logo.png
• logo-light.png

To customize the Developer Portal theme, either modify these three files or specify a new folder in the DSAPI.yml file:

# Portal themes
portal:
  themes:
    path: ${DSAPI.home}/themes

By default, this configuration is commented out and the path is ${DSAPI.home}/themes.

For assistance creating a theme, use the editor in Settings > Theme and export it to a JSON file via the EXPORT button in the header menu. Keep in mind:

• Images and logos cannot be changed using this method. The two files must be edited in the distribution.
• Exported themes do not have the same format as the provided definition.json file, requiring minor edits to the exported theme.

Expected format:

{
  "data": [
    {
      "name": "gv-theme",
      "css": [
        {
          "name": "--gv-theme-color-darker",
          "description": "Primary darker color",
          "type": "color",
          "default": "#383E3F",
          "value": "#383E3F"
        },
        ...
      ]
    },
    ...
  ]
}

Configuring the Developer Portal Settings

Configure settings

1. Log in to the Management Console

2. Select Settings from the left sidebar

3. Select Settings from the inner left sidebar

   

4. Scroll down to the Portal header

   

5. Configure the settings described below:

• Api-key Header: Modify the api-key header shown in the Developer Portal's CURL commands. This only impacts what is displayed in the Developer Portal's UI. You must modify the DSAPI.yaml file to change how the Gateway handles the api-key header.

• Portal URL: Enter the URL of the Developer Portal. This will add a link to the Developer Portal on the top navigation bar of the Management Console. Additionally, the theme editor will show a live preview of the Developer Portal.

  

• Override homepage title: Toggling to ON allows you to change the Developer Portal title from "Unleash the power of your APIs." to a custom title

• Options

  • Use Tiles Mode: Sets the default view of APIs to tiles as opposed to a list
  • Activate Support: Adds a Contact and Tickets tab to each API. Email must be configured per the Email configuration section to use the contact form.
  • Activate Rating: Allow API consumers to leave written reviews and ratings
  • Force user to fill comment: Requires all subscription requests to include a comment
  • Allow User Registration: Allow API consumers to create an account from the Developer Portal. Email must be configured per the Email configuration section to enable registration.
    • Enable automatic validation: Automatically approve all accounts created on the Developer Portal
  • Add Google Analytics: Add a Google Analytics tracking ID to the Developer Portal
  • Allow Upload Images: Allows documentation owners to attach images as additional resources
  • Max size upload file (bytes): Controls the size of images that documentation owners are allowed to attach

• OpenAPI Viewers: Choose a viewer to display your API documentation

• Schedulers: Configure the frequency with which the Developer Portal runs background tasks such as syncing data and sending/receiving notifications

• (v2 APIs only) Documentation URL: Set the URL shown at the end of the v2 API creation flow

  

APIM Developer Portal

Configuration file

The configuration file for APIM Portal is assets\config.json. The default configuration is shown below:

{
  "baseURL": "/portal/environments/DEFAULT",
  "homepage": {
    "featured": {
      "size": 9
    }
  },
  "loaderURL": "assets/images/DSAPI-loader.gif",
  "pagination": {
    "size": {
      "default": 10,
      "values": [5, 10, 25, 50, 100]
    }
  }
}

The only mandatory value in config.json file is baseURL, which describes the location of the APIM API Portal endpoint. You must set this value for APIM Portal to send requests to the endpoint.

Creating and maintaining applications with DSAPI Developer Portal

For more information about creating and maintaing applications, see the following articles:

Creating an application with the DSAPI Developer Portal

Overview

Unless the API has a keyless plan, a consumer must register an application and subscribe to a published API plan to access an API. Applications act on behalf of the user to request tokens, provide user identity information, and retrieve protected resources from remote services and APIs.

Create an application

1. In the Developer Portal, click on Applications in the header

   

2. On the General page, specify:

   • Application name: Give your application a name (required)
   • Description: Describe the purpose of your application (required)
   • Domain used by the application: Enter the domain to be used by the application or keep the pre-filled default
   • (Optional) Application Image: Select an image for your application

   

3. Select the appropriate tile to configure security for the type of software application you're registering your application for. Each application type requires you to set certain parameters.

A Simple application is hands-free. With this application, you have the ability to define the client ID.

Parameters:

• Type: Enter the type of application (mobile, web, etc.).
• Client ID: Enter the client ID of the application. This field is required to subscribe to certain API plans (OAuth2, JWT).

A SPA, or single-page application (Angular, React, etc.), is a web application that performs the majority of the user interface logic in a web browser and uses web APIs to communicate with the web server.

Parameters:

• Toggle Authorization Code and Implicit to enable the types of rights authorized for the client. For security, define only the types you need.
• Use the + icon to add Redirect URIs where the authorization server will send OAuth responses.

Until you add a Redirect URI, a red "x" will appear in lieu of the green checkmark above Security:

A traditional Web application (Java, .Net, etc.) performs the majority of the application logic on the server.

Parameters:

• Toggle Authorization Code, Refresh Token, and Implicit (Hybrid) to enable the types of rights authorized for the client. For security, define only the types you need.
• Use the + icon to add Redirect URIs where the authorization server will send OAuth responses.

Once you add a Redirect URI, a green checkmark will appear in lieu of the red "x" above Security.

A Native application (iOS, Android, etc.) can be installed directly on a mobile device.

Parameters:

• Toggle Authorization Code, Refresh Token, Resource Owner Password, and Implicit (Hybrid) to enable the types of rights authorized for the client. For security, define only the types you need.
• Use the + icon to add Redirect URIs where the authorization server will send OAuth responses.

Once you add a Redirect URI, a green checkmark will appear in lieu of the red "x" above Security.

A Backend to backend application is machine to machine and does not require a user interface.

Parameters:

• Toggle Client Credentials to enable the types of rights authorized for the client. For security, define only the types you need.

4. Use the search field to find an API for your application, then subscribe to it. Optionally, you can leave a comment for the API owner.

   

5. Review the information you entered, then click CREATE THE APP:

   

Application options

Once you've created an application, you can click on it and use the header options to review and edit the details of its configuration and usage:

• General information: View and/or modify the application's configuration.

  

• Metadata: Enter a Name and Value and use the Format selector to define metadata for your application. Use the ADD and UPDATE buttons to modify your entries.

  

• Subscriptions: View the APIs your application is subscribed to. Use the API drop-down menu to choose a particular API and the status drop-down menu to list all APIs with the selected status.

  

• Members: View and edit member information:

  • MEMBERS LIST: View the names and roles of current application members.

    

  • ADD A MEMBER: Use the search field to add a member to the application and assign that member a role.

    

  • TRANSFER OWNERSHIP: Transfer ownership of the application to another user and select a different role for the current primary owner.

    

  • INHERITED MEMBERS: View the names and roles of members inherited from other groups.

    

• Analytics: Use the available filters to refine the application logs. Scroll down to view other metrics related to the application (top paths, top APIs, response times, etc.).

  

• Logs: Use the available filters to view and optionally export refined application analytics. Scroll down to view the logs.

  

• Notifications: Specify which of your application's subscription events you would like to be notified of.

  

• Alerts: Use the fields and drop-down menus to define an alert. After you ADD AN ALERT, it will appear in the ALERTS LIST. Application members will be notified via email.

  

Publishing and managing APIs with the DSAPI Developer Portal

You can publish and maintain APIS with the DSAPI Developer Portal. For more infomation about publishing APIs, see the following articles:

Publishing your API with the DSAPI Developer Portal

Access API

First, we need to open the API in the APIM Console. You may already have it open from the previous part of the Quickstart Guide. If not, head back over to the APIs homescreen and select the API you created.

• Select APIs in the sidebar
• Select the API you created in Gateway APIs 101

Publish API

This will take you straight to your API's General Info page. In the Danger Zone, we can update the visibility of the API:

• Publish/Unpublish the API: This is a toggle that controls the visibility of the API in the Developer Portal. Unless the API is also public, it is only visible to members of the API, which is controlled through User and group access in the inner sidebar.
• Make Public/Private: This is a toggle that makes the API visible to anyone with access to the Developer Portal. Note, this toggle only has an impact if the API is published.

• Click Publish the API, then Publish in the modal to add the API to the Developer Portal
• Click Make Public, then Make Public again in the modal, to make the API visible to all API consumers

Managing API documentation with the DSAPI Developer Portal

Overview

Site-wide documentation creates a direct line of communication with your developer community. Administrators can use site-wide documentation to communicate best practices, configure pages, or as a reference via custom navigation. Published documentation is accessible from the Developer Portal's Documentation page:

The following sections discuss how to:

• Create documentation
• Generate content
• Import multiple pages
• Page management

Create documentation

To create documentation:

1. Select Settings from the left sidebar of the Management Console

2. Select Documentation from the inner left sidebar

   

3. Select the + icon on the bottom right to display the options below.

   

• Folder: Generate a folder to organize your documentation. Optionally generate translations of the folder by selecting Translate Folder.

  

• Markdown Template: Create templates reusable for site-wide and API Markdown documentation.

• Markdown: Use the Markdown syntax for the documentation page.

• AsciiDoc: Use the Asciidoc syntax for the documentation page.

• OpenAPI (Swagger): Use the OpenAPI syntax for the documentation page.

• AsyncAPI: Use the AsyncAPI syntax for the documentation page.

Each documentation type provides similar configuration options and a compatible text editor.

• Name: Provide a title for your documentation page.

• Set as homepage: Use the documentation page as the homepage of the Developer Portal. If multiple documentation pages are set as the homepage, the page most recently set will be selected.

  

• Publish this page: Make the page available in the Developer Portal.

• Make private: Make the page private to you and the users you explicitly allow using access control.

Generate content

APIM provides three methods for generating documentation content:

• Fill the content inline (supports templating with API properties)
• Import from file
• External source (Gitlab, Bitbucket, etc.)

This method uses the text editor to generate content based on your selected documentation type. In addition, APIM supports templating with API properties.

Templating with API properties

Use the following syntax to access the API data in your API documentation: ${api.name} or ${api.metadata['foo-bar']}.

The sample script below creates a documentation template based on the Apache FreeMarker template engine:

<#if api.picture??>
<img src="${api.picture}" style="float: right;max-width: 60px;"/>
</#if>

# Welcome to the API ${api.name}(${api.version})!

The API is <span style="text-transform: lowercase;color: <#if api.state=='STARTED'>green<#else>red</#if>">${api.state}</span>.

This API has been created on ${api.createdAt?datetime} and updated on ${api.updatedAt?datetime}.

<#if api.deployedAt??>
This API has been deployed on ${api.deployedAt?datetime}.
<#else>
This API has not yet been deployed.
</#if>

<#if api.visibility=='PUBLIC'>
This API is publicly exposed.
<#else>
This API is not publicly exposed.
</#if>

<#if api.tags?has_content>
Sharding tags: ${api.tags?join(", ")}
</#if>

## Description

${api.description}

<#if api.proxy??>
## How to access

The API can be accessed through https://api.company.com${api.proxy.contextPath}:

curl https://api.company.com${api.proxy.contextPath}
</#if>

## Rating

You can rate and put a comment for this API <a href='/#!/apis/${api.id}/ratings'>here</a>.

## Contact

<#if api.metadata['email-support']??>
The support contact is <a href="mailto:${api.metadata['email-support']}">${api.metadata['email-support']}</a>.
</#if>

The API owner is <#if api.primaryOwner.email??><a href="mailto:${api.primaryOwner.email}">${api.primaryOwner.displayName}</a><#else>${api.primaryOwner.displayName}</#if>.

The above sample script creates the following in the Developer Portal:

API properties reference

The following reference table shows all available API properties. Access these properties in the Freemarker template with ${api.<Field name>} as in the above sample script.

Field name	Field type	Example
id	String	70e72a24-59ac-4bad-a72a-2459acbbad39
name	String	My first API
description	String	My first API
version	String	1
metadata	Map	{"email-support": "support.contact@company.com"}
createdAt	Date	12 juil. 2018 14:44:00
updatedAt	Date	12 juil. 2018 14:46:00
deployedAt	Date	12 juil. 2018 14:49:00
picture	String	data:image/png;base64,iVBO…​
state	String	STARTED/STOPPED
visibility	String	PUBLIC/PRIVATE
tags	Array	["internal", "sales"]
proxy.contextPath	String	/stores
primaryOwner.displayName	String	Firstname Lastname
primaryOwner.email	String	firstname.lastname@company.com

This method allows you to import your documentation from external sources. APIM includes five types of fetchers:

• GitHub: Fetch your documentation from a GitHub repository
• GitLab: Fetch your documentation from a GitLab repository
• Git: Fetch your documentation from any Git repository
• WWW: Fetch your documentation from the web
• Bitbucket: Fetch your documentation from a Bitbucket repository

The documentation is fetched and stored locally in APIM in the following three scenarios:

• Once, after you finish configuring your fetcher

• Any time you select Fetch All on the Documentation page

  

• At regular intervals when auto-fetch is configured

Import multiple pages

If you have existing documentation for your API in a GitHub or GitLab repository, you can:

• Configure the GitHub or GitLab fetcher to import the complete documentation structure on a one-off or regular basis
• Import the documentation into APIM in a structure different from that of the source repository by:
  • Creating a DSAPI descriptor file (.DSAPI.json) at the repository root that describes both the source and destination structures
  • Configuring a fetcher in APIM to read the JSON file and import the documentation according to the structure defined in the file

{
    "version": 1,
    "documentation": {
        "pages": [
            {
                "src": "/newdoc/readme.md",
                "dest": "/",
                "name": "Homepage",
                "homepage": true
            },
            {
                "src": "/test-import-swagger.json",
                "dest": "/technical",
                "name": "Swagger"
            }
        ]
    }
}

Page management

Select a page to configure the following via the header tabs:

• Page: Manage the content of the documentation page by via the inline editor or by importing files
• Translations: Add translations of your page
• Configuration: Toggle options to publish your page and use it as the homepage
• External Source: Configure a fetcher for the page
• Access Control: Fine-grained access control over your page
• Attached Resources: Add additional files to your documentation page.
  • This requires the administrator to configure Allow Upload Images and Max size upload file (bytes) in general settings.

Page, Translations and Access Control are described in greater detail below.

If incorrect templating is applied to the Markdown page of an API, errors are generated to alert the user that the page will not be formatted as intended when published to the Developer Portal.

You can add translations for your pages via the Translations tab:

1. Select Add a translation
2. Enter your 2-character language code (FR for French, CZ for Czech, IT for Italian, etc.)
3. Enter the translated title
4. (Optional) You can edit the content to add translated content by toggling on the switch
5. Click Save Translation at the bottom of the page

{% tab title="Access control" %} From the Access Control tab:

• You can mark a page as Private if you want to deny access to anonymous users.
• If a page is Private, you can configure access lists to either require or exclude certain roles and groups by toggling the Excluded option.

Configuration

Introduction

APIM components can be configured using:

1. Environment variables
2. System properties
3. The DSAPI.yaml file

Environment variables

You can override the default APIM configuration (DSAPI.yml) and system properties by defining environment variables. Any property in the yaml file can be translated to an environment variable by prefixing the property with "DSAPI" and using camel_case or dot notation.

management:
  mongodb:
    dbname: myDatabase

DSAPI_management_mongodb_dbname=myDatabase
DSAPI.management.mongodb.dbname=myDatabase

analytics:
  elasticsearch:
    endpoints:
      - https://my.first.endpoint.com
      - https://my.second.endpoint.com

security:
  providers:
    - type: ldap
      context-source-username: "cn=Directory Manager"
      context-source-password: "password"

DSAPI_analytics_elasticsearch_endpoints_0=https://my.first.endpoint.com
DSAPI_analytics_elasticsearch_endpoints_1=https://my.second.endpoint.com

DSAPI_security_providers_0_type=ldap
DSAPI_security_providers_0_contextsourceusername=cn=Directory Manager
DSAPI_security_providers_0_contextsourcepassword=password

DSAPI.analytics.elasticsearch.endpoints[0]=https://my.first.endpoint.com
DSAPI.analytics.elasticsearch.endpoints[1]=https://my.second.endpoint.com

DSAPI.security.providers[0]type=ldap
DSAPI.security.providers[0]context-source-username=cn=Directory Manager
DSAPI.security.providers[0]context-source-password=password
DSAPI.security.providers[0].users[1].password=password

System properties

You can override the default APIM configuration (DSAPI.yml) by defining system properties.

management:
  mongodb:
    dbname: myDatabase

-Dmanagement.mongodb.dbname=myDatabase

The DSAPI.yaml file

The DSAPI.yaml file, found in DSAPI_HOME/config/, is the default way to configure APIM.