Building Developer Portal Site

This article will guide you on how to publish an API that has already been integrated with the API7 Gateway to the developer portal associated with the gateway. You will set up a site that allows internal or external developers to log in and find this API, view its corresponding documentation, and apply to subscribe to the API. Once approved by the API administrator, developers will automatically obtain access credentials.

Why Need a Developer Portal

API lifecycle management should not only focus on simplifying API management, but also address the issue of API consumption, specifically how external developers (including those from different teams within the same company) can easily integrate the API. Let's consider what problems need to be addressed to allow an external developer to call your API.

The first issue is how to allow external developers to access API information, including the API endpoint, description, parameter constraints, and usage examples. Providing these details can effectively help external developers understand and use the API.

The second issue is that API providers typically do not want anyone to be able to call the APIs. They want to protect the API and ensure that external developers can only use it with valid API credentials. Moreover, they want the process of API consumption to be as self-service as possible, reducing the costs associated with communication and collaboration.

To optimize the API consumption process, the concept of a developer portal has been introduced to address the aforementioned problems. API7 Enterprise has launched its own developer portal product, designed to work in conjunction with the gateway.

Background Information

Get to know the key concept of the developer portal.

Architecture

• The open platform shown in the diagram needs to be developed separately or integrated into an existing business platform. It can support multiple business platforms simultaneously. For example, you can build an intranet open platform to manage APIs used only within the organization, and also build a public open platform to manage APIs exposed to external users. Alternatively, you can create independent sites for specific organizations or departments to manage APIs used exclusively by them, based on their business requirements.
• The API7 Developer Portal display site provides back-end APIs only and does not store developer account-related information unless the built-in email account system is enabled (not recommended).
• The API7 Developer Portal admin site provides front-end pages and backend, which can be accessed by logging into the API7 Enterprise dashboard.

Calling Display Site APIs

Sequence Diagram

API Authorization

Authorization is required when calling the backend API of the display site to ensure security.

API7 Developer Portal utilizes JWT authorization. The authorization process consists of two parts: obtaining the access_token and including the token in the request.

Obtain the Access Token

1. Generate the access_token using a specific code snippet, which requires passing the organization ID information. The secret needs to match the one in API7-Devportal.

For example:

func GenerateToken(userID, secret string, expiredIn int) (string, error) {
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
       "org_id": orgID,
       "iat": jwt.NewNumericDate(time.Now()),
       "exp": jwt.NewNumericDate(time.Now().Add(time.Second * time.Duration(expiredIn))),
    })

    return token.SignedString([]byte(secret))
}

2. Call the token issuance API, which also requires providing the organization ID information. API7 Developer Portal will extract the organization ID information from the access_token and return the corresponding information under that organization.

For example:

curl -XPUT http://127.0.0.1:9000/devportal/sign  -H "Authorization: Bearer $root_access_token" -d 
'{
    "org_id": "$orgID"
}'

Access the Access Token

Including it in the Authorization header:

curl http://127.0.0.1:9000/devportal/applications -H "Authorization: Bearer $access_token"