Application Creation
Creating the Developer Portal using the Mia-Platform Console is extremely simple. With just a few clicks and almost no configuration, you will be able to create all the necessary resources composing the Dev Portal architecture.
Integration requirements
To integrate the Dev Portal, you only need to be able to access the project from which it will be exposed.
Integration steps
To deploy a Dev Portal instance on the Mia Platform Console, you will have to:
- create the Dev Portal application;
- configure the theming properties of micro-lc;
- configure redirects;
- configure API documentation, authentication, and notifications (optional).
1. Create Dev Portal Application
The first fundamental requirement for a correct Dev Portal configuration is creating the Dev Portal application through the Marketplace.
The following steps will lead you to create an instance of the Dev Portal application:
Open the
Design
area of your projectMove to the
Application
section;Create a new application using the Dev Portal application available in the
Core Plugins - Dev Portal
section of the marketplace:Configure the name and the description for both the application and all the microservices composing it:
Review the creation of all the resources composing the application (microservices, endpoints, collections and public variables):
Complete the creation of the Dev Portal application by clicking
Create
.
2. Configure dev-portal-micro-lc-backend
After creating the Dev Portal application, you will be able to customize it with your logos and default theme colors.
The following steps will lead you to the configuration of the theming properties used by the Dev Portal.
Go to the
Microservices
sectionOpen the detail of the microservice originally named
dev-portal-micro-lc-backend
;Move to the
ConfigMaps
sectionEdit the theming property of the file
configuration.json
;cautionThe remaining configurations are already set for the
Dev Portal
: to know more about their purpose, please consult theCore Configuration
section ofmicro-lc
.
3. Configure Redirects
For this configuration step, move to the Advanced section of the console and select the api-gateway
microservice.
These endpoints allow the two micro-lc instances, created respectively for the Backoffice and Dev Portal sections, to exist simultaneously without conflicts.
Search for the following files and paste the content below:
- maps-proxyUrl.before.map
# micro-lc Dev Portal
"~^\w+-/dev-portal/.+/api/v1/microlc(?<path>[/\?].*|$)$" "/v1/microlc$path";
# micro-lc Backoffice
"~^\w+-/back-office/.+/api/v1/microlc(?<path>[/\?].*|$)$" "/v1/microlc$path";
# micro-lc user info
"~^\w+-/.+/userinfo(?<path>[/\?].*|$)$" "/userinfo$path";
- maps-proxyName.before.map
# micro-lc Dev Portal
"~^(secreted|unsecreted)-1-GET-/dev-portal/.*/api/v1/microlc/.*" "dev-portal-micro-lc-backend";
# micro-lc Backoffice
"~^(secreted|unsecreted)-1-GET-/back-office/.*/api/v1/microlc/.*" "backoffice-micro-lc-backend";
# micro-lc user info
"~^(secreted|unsecreted)-1-\w+-/.*/userinfo([/\?].*|$)$" "auth0-client";
- root-location-extension.conf
location = / {
include /etc/nginx/customization.d/header-debug.conf;
return 302 '$original_request_scheme://$original_request_host/dev-portal/';
}
location = /dev-portal {
include /etc/nginx/customization.d/header-debug.conf;
return 302 '$original_request_scheme://$original_request_host/dev-portal/';
}
location = /back-office {
include /etc/nginx/customization.d/header-debug.conf;
return 302 '$original_request_scheme://$original_request_host/back-office/';
}
Please ignore any red feedback that may appear when pasting this content within the advanced section files.
Final result
At the end of these steps, the configuration of your project should include all the resources listed in the following sections.
Microservices
The complete configuration of the Developer Portal will include the following microservices:
Microservice | Version | Description |
---|---|---|
API Gateway | 5.0.0 | routes requests to the correct service and verifies the need of authentication. |
API Portal | 1.16.3 | shows the exposed APIs' documentation in the Dev Portal section. |
Aggregated Dev Portal Frontends | 0.4.2 | present graphically both the Backoffice and the Dev Portal sections. |
Backoffice Micro-lc Backend | 0.7.0 | manage the Backoffice section. |
Crud Service | 5.2.2 | manage the crud operations. |
Dev Portal Marketplace Backend | 0.2.1 | manage the API marketplace section. |
Dev Portal Micro-lc Backend | 0.7.0 | manage the Dev Portal section. |
Dev Portal Micro-lc Docusaurus | x.x.x | displays the documentation inside the Dev Portal. |
Files Service | 2.3.4 | handles files upload and download operations in the Backoffice section. |
Microservice Gateway | 6.0.6 | provides the ability to specify HTTP hooks to be invoked before and after each request. |
Swagger Aggregator | 3.4.4 | expose the APIs' documentations of your microservices. |
When you create a Dev Portal application with already existing services, the version of these services will not be automatically upgraded.
Make sure the microservices in your project use the versions specified above. A Dev Portal application deployed with different versions may not be able to work properly.
Endpoints
The complete configuration of the Developer Portal will include the following endpoints:
Aggregated Frontend Plugins
The APIs necessary for the Dev Portal frontend:
Endpoint | Microservice | Rewrite Base Path |
---|---|---|
/ | aggregated-dev-portal-frontends | / |
Backoffice
The APIs necessary for the management of the Backoffice section:
Endpoint | Microservice | Rewrite Base Path |
---|---|---|
/back-office/api | backoffice-micro-lc-backend | / |
/files | files-service | / |
Dev Portal
The APIs necessary for the management of the Dev Portal section:
Endpoint | Microservice | Rewrite Base Path |
---|---|---|
/dev-portal/api | dev-portal-micro-lc-backend | / |
/bff | dev-portal-marketplace-backend | / |
/docusaurus | dev-portal-micro-lc-docusaurus | / |
/documentation/assets | dev-portal-micro-lc-docusaurus | /assets |
/dev-portal/documentation/assets | dev-portal-micro-lc-docusaurus | /assets |
/dev-portal/api-portal/api | swagger aggregator | / |
/dev-portal/documentation/search-index.json | dev-portal-micro-lc-docusaurus | /search-index.json |
CRUD Endpoints
The APIs necessary for the management of the CRUD operations:
Endpoint | CRUD Collection |
---|---|
/components | components |
/categories | categories |
/tags | tags |
/requests | requests |
/icons | icons |
CRUD Collections
The data model used for the management of the Developer Portal will include four collections:
Components
This collection is used to store the components that will be displayed in the marketplace. Excluding the default properties of the CRUD (_id, creatorId, createdAt, updaterId, updatedAt, STATE), the defined fields are:
- title: the title of the component;
- icon: the object that contains the file icon definition. For more detail, refer to the icons section;
- type: the type of the component (API, Event...);
- category: the category to which the component belongs;
- tags: the tags to which the component is associated to;
- description: the description of the component, that will be displayed in the component detail;
- linkApiPortal: the URL used to redirect the user to the API portal;
- linkDocumentation: the URL used to redirect the documentation portal;
- supporterName: name of the entity that supports the component;
- supporterIcon: the object that contains the supporter icon definition. For more detail, refer to the icons section.
Categories
This collection is used to save the name and description of the categories that can be used to group your components inside the marketplace. Excluding the default properties of the CRUD (_id, creatorId, createdAt, updaterId, updatedAt, STATE), the defined fields are:
- name: Contains the name of the category;
- description: Contains the description of the category.
Tags
This collection is used to save the name and description of the tags that can be used to enrich your components inside the Marketplace. Excluding the default properties of the CRUD (_id, creatorId, createdAt, updaterId, updatedAt, STATE), the defined fields are:
- name: Contains the name of the tag;
- description: Contains the description of the tag.
Requests
This collection is used to save the access requests to your components, made from the components marketplace. Excluding the default properties of the CRUD (_id, creatorId, createdAt, updaterId, updatedAt, STATE), the defined fields are:
- userEmail: the email of the user that is requesting the access;
- userName: the name of the user that is requesting the access;
- status: the current status of the request (open, completed...);
- userOrganization: the organization to which the user belongs to;
- requestedComponentId: ID of the component that the user wants to access;
- publicKey: the RSA public key of the user that is requesting the access;
- additionalDescription: an additional description field to include further details regarding the request.
Icons
This collection is used to save the icons associated with each component. Excluding the default properties of the CRUD (_id, creatorId, createdAt, updaterId, updatedAt, STATE), the defined fields are:
- name: the original name of the uploaded file;
- size: the size of the uploaded file;
- location: the location of the file on the bucket;
- file: the name of the file on the bucket.
Public Variables
The complete configuration of the Developer Portal will include the following public variables:
Variable | Description |
---|---|
BACKOFFICE_WEB_COMPONENTS_VERSION | the version of the Backoffice components used in the `backoffice-micro-lc-backend` configurations. |