ENDOC-524 7.1 Ent CLI-create new API management page #540
Conversation
|
|
||
| Common operations associated with API claims are detailed below. | ||
|
|
||
| The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional information. |
|
|
||
| - `name` and `type` correspond to the same fields in the API claim source descriptor | ||
| - `pluginName` corresponds to `serviceName` | ||
| - `bundleId` is a generated ID derived from the bundle |
There was a problem hiding this comment.
Might be good to link this to the bundleId generation section.
| "name": "ext-api", | ||
| "type": "external", | ||
| "serviceName": "ext-ms", | ||
| "bundle": "registry.hub.docker.com/my-org/my-entando-bundle" |
There was a problem hiding this comment.
Open question: can this only reference other bundles within the same project/namespace? We might need @w-caffiero-entando to comment but "external" sounds like it could be external to this bundle (as it appears) or external to this project/namespace - say to other projects or even outside kubernetes to other enterprise systems or even to external 3rd party services in the cloud. Based on the format of the bundles I suspect it's only the first case but we should probably add a clarifying note on the scope.
There was a problem hiding this comment.
In this context external means external to the bundle, but not to the Kubernetes namespace. Indeed, when you execute ent bundle api add-ext you have to be connected to an Entando instance and the command will fail if it sees that the service you are specifying in the API claim doesn't exist on the cluster. The external service has to be deployed before adding its API claim.
There was a problem hiding this comment.
When you execute the command without the flags it searches the available services on the instance, so that you can select one of them interactively:
The command also displays that you are running it on a given instance.
|
|
||
| ``` yaml | ||
| apiClaims: | ||
| - name: int-api |
There was a problem hiding this comment.
what are these red bars?
|
|
||
| | Command | Description | ||
| | :- | :- | ||
| | `api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE |
There was a problem hiding this comment.
[mfe-name] >> YOUR-MFE-NAME
[claim-name] >> YOUR-CLAIM-NAME
since these are place holders, I've been using the all caps format with YOUR attached, and no brackets.
|
|
||
| An API claim informs the Entando Platform that a microfrontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. |
|
|
||
| An API claim informs the Entando Platform that a micro frontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. |
There was a problem hiding this comment.
I think that the definition is correct, however at the moment our commands allow to define an API claim only from a MFE to a MS and not from a MS to another MS.
| - `bundle`: The external bundle URL | ||
| - `service-name`: The name of a microservice in the external bundle. If `service-name` is not set, `api add-ext` will initiate an interactive mode where the user can select from available bundles and microservices. | ||
|
|
||
| ## API Claim YAML Descriptor Mapping |
There was a problem hiding this comment.
I don't think that a user of the CLI is interested in this. It is mostly an internal implementation detail. The YAML descriptors are generated by the pack command (inside a hidden directory) and used to build the bundle image. What we did with the "descriptor mapping" is a conversion that is useful to us for keeping compatibility between the new entando.json format and the old bundle format made by YAML descriptors. Users of the new CLI will never edit these files.
Instead, I think a user that is creating a new bundle may be interested in knowing how he or she can retrieve the URL of the MS to call from the MFE JavaScript code. I would write something like this:
A microfrontend installed from a bundle is rendered by Entando using a custom HTML element. Entando injects inside the config attribute of this element a JSON object containing configuration details, e.g.:
<my-mfe config="{ ... }" />
Inside the JavaScript code of a MFE, the URL of a MS declared through API claims can be retrieved accessing the following element of the config object:
systemParams.api[claimName].url
Where claimName is the name you have chosen when you defined the API claim. Please consider that this is only an example. Have a look at demo bundles code for more robust ways to retrieve this value (considering also cases when the parent object is not defined).
When you are testing your MFE locally, the URL is different and it is retrieved from the mfe-config.json file located inside MFE public folder. This file is automatically updated by the commands that add and remove API claims. Example of a generated mfe-config.json:
{
"systemParams": {
"api": {
"my-api-claim": {
"url": "http://localhost:8082"
}
}
}
}
Remember that this configuration file is used only for local testing. When the bundle will be installed the configuration data is provided by the Entando instance.
| | :- | :- | ||
| | `ent bundle api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE | ||
| | `ent bundle api add-ext [mfe-name] [claim-name]` | Add an external API claim to an MFE | ||
| | `ent bundle api rm [mfe-name] [claim-name]` | Remove an API claim from an MFE |
There was a problem hiding this comment.
I would also add a note about the fact that all ent bundle api subcommands can be executed only if the user is attached to a running Entando (see ent attach commands), otherwise the CLI will produce an authentication error.
There was a problem hiding this comment.
@jyunmitch Minor, might be better to write ent attach-* since the exact commands are attach-vm, attach-kubeconfig, attach-kubectx
| | :- | :- | ||
| | `ent bundle api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE | ||
| | `ent bundle api add-ext [mfe-name] [claim-name]` | Add an external API claim to an MFE | ||
| | `ent bundle api rm [mfe-name] [claim-name]` | Remove an API claim from an MFE |
There was a problem hiding this comment.
@jyunmitch Minor, might be better to write ent attach-* since the exact commands are attach-vm, attach-kubeconfig, attach-kubectx
|
|
||
| To retrieve the URL of an MS declared through an API claim, add `systemParams.api[claimName].url` to the MFE JavaScript code so it can access that element of the config object. The `claimName` was chosen by the user when the API claim was defined. | ||
|
|
||
| Refer to the Entando demo bundles for alternative retrieval methods. These techniques are more robust and consider cases where the parent object is not defined. |
There was a problem hiding this comment.
these techniques>> "These" techniques are referring to the alternative retrieval method ones, right? just checking
There was a problem hiding this comment.
yes, but i'll combine those 2 sentences to clarify
No description provided.