Introduction¶
Anypoint tools is able to automatically setup all API Management configuration for an API when it deploys it.
In order to use this feature, you will need to add an anypoint.json, anypoint.yml or anypoint.yaml file to your project root folder (alongside pom.xml).
This file needs to have at least an empty object, and it is highly recommanded to specify the $schema property as shown below (that way you can use )
You will then be able to add all the API Management configuration to that file. The following documentation will be based on a JSON file, but you also are able to use the equivalent in YAML.
For the full schema definition, see Application descriptor schema definition
Application parameters¶
By default, the application id will be assigned to be the same as your project's pom.xml artifact id, but you can also override it as shown below:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"id": "my-application-name"
}
API Definition¶
In order to have your API provisioned with API Manager, you will need to create an "api" section in your anypoint.json as shown in the example below:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"asset": {
"id": "my-app-spec",
"version": "1.0.0",
"apiVersion": "v1",
"name": "My App",
"description": "App that does stuff",
"tags": [
"foo",
"bar"
],
"portal": {
"pages": [
{
"name": "home",
"content": "# Hello"
}
]
},
"categories": {
"color": [
"blue",
"red"
]
},
"fields": [
{
"key": "author",
"value": "me",
"required": false
}
],
"icon": {
"path": "icon.svg",
"mimeType": "application/svn"
},
"create": true,
"type": "REST",
"assetMainFile": "swagger.json"
},
"implementationUrl": "https://apiserver:8081",
"consumerUrl": "https://api.myorg.com/myapi",
"tags": ["foo","bar"],
"addAutoDiscovery": true,
"autoDiscoveryFlow": "api-main",
"policies": [
{
"policyTemplateId": "fadsfdsfds",
"groupId": "423324342342",
"assetId": "somepolicy",
"assetVersion": "1.1",
"configurationData": {
"foo": "bar"
}
}
],
"accessedBy": ["adminclient"],
"label": "foo",
"slaTiers": [
{
"name": "MyTier",
"description": "My SLA Tier",
"autoApprove": true,
"limits": [
{
"visible":true,
"timePeriodInMilliseconds": 1,
"maximumRequests": 1
}
]
}
]
}
}
Many of those values however have smart defaults, so you don't actually need to specify all of them and your spec can be as short as:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
}
}
Open the following section for information on how default values are generated:
Default values
| Property | Default Value |
|---|---|
| apiVersion | This will be generated based on the asset version (specifically the major version element of the version). If the spec is OAS the api version will be [MAJORVERSION].0.0, otherwise it will use v[MAJORVERSION]. So for example an OAS spec with an asset version of 1.3.1 will have have an API version of 1.0.0 |
Asset¶
In order to create an API, an exchange asset must be present in exchange.
There's three approaches to fulfill this requirement (open the relevant sections for details):
Specification managed separately from project
This is the typical use case where developers create an API project from an asset that is already published in exchange (for example by having the developer create/publish the spec from Design Center).
When using this approach EMT will automatically find the asset details from your pom so you don't need to create the asset section.
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
}
}
However if for some reason you need to specify groupId / assetId / version you can do so as shown below:
API Specification in project
In this approach, developers can keep the API specification in their project in the src/main/resources/api
folder, and when the application is published the specs will be automatically uploaded in exchange if:
- There isn't already a specification with the same group id / asset id / version
- The version is NOT a snapshot
API specifications with a SNAPSHOT version will automatically modify the version to include a timestamp after the SNAPSHOT element of the version (so they will always be unique every time a deployment happens).
So for example if you have asset 1.0.1-SNAPSHOT, when it published it the asset will something like
1.0.1-SNAPSHOT-20221112010522
If you spec file is either api.[extension] or [assetId].[extension], then it will default assetMainFile to
that file, and set create to true (ie if you project is my-app you can just create RAML file my-app-spec.raml)
, otherwise you will need to specify those as below:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"asset": {
"assetMainFile": "my-api.raml",
"create": true
}
}
}
This will automatically default the asset properties as shown below:
| Property | Default Value |
|---|---|
| groupId | the groupId of the business group the application is deployed to |
| id | application artifactId appended with -spec |
| version | version element from application pom.xml |
| description | description field from application pom.xml |
| name | name field from application pom.xml |
Additionally you can specify various exchange asset details like pages, tags, categories, icon, etc. See schema for details
Have no specification and have EMT create an exchange 'HTTP' asset (instead of the 'REST' asset)
If you don't have an API specification, you can just set the asset type to http and create to true
Other API configuration attributes¶
- endpoint: The API endpoint
- label: The API label
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"endpoint": "http://myapi/v1/",
"label": "prc"
}
}
API Autodiscovery configuration¶
Since EMT only provisions the API in API Manager and inject API id as part of deployment, this cannot be used when running the application locally.
To work around this problem you can either NOT add auto-discovery to your project and have EMT add it at deployment time
by setting the addAutoDiscovery flag to true, and autoDiscoveryFlow to the name of your APIKit flow. ie:
Or alternatively add auto-discovery to your project, disable gatekeeper in your JVM parameters:
and set the property anypoint.api.id to any value. For example add to properties-local.yaml:
Policies¶
You can add policies to your configuration file as shown below:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"assetId": "my-api",
"assetVersion": "1.0.0",
"endpoint": "http://myapi/xxx",
"policies": [
{
"groupId": "68ef9520-24e9-4cf2-b2f5-620025690913",
"assetId": "header-injection",
"assetVersion": "1.0.0",
"policyTemplateId": "59",
"type": "json",
"configurationData": {
"inboundHeaders": [
{
"key": "foo",
"value": "bar"
}
]
}
}
]
}
}
The type should always be JSON, and the json payload will depend on which policy you're including. See the following details to find out the JSON structure of any policy you wish to use.
How to find the policy JSON configuration structure
In order to find the JSON payload, you should create an API using the policy you wish to use, and either use EMT cli, or use a browser's debug tools.
You will need to go to anypoint and use your web browser's debug capabilities ( for example Developer Tools in chrome ) and create your desired policy while it's recording network activity.
You should see it doing a POST to an url
like: https://anypoint.mulesoft.com/apimanager/api/v1/organizations/[yourorgid]/environments/{yourenvid}/apis/15694893/policies
With a payload containing all the policy configuration, for example:
{
"configurationData": {
"credentialsOriginHasHttpBasicAuthenticationHeader": "customExpression",
"clientIdExpression": "#[attributes.headers['client_id']]",
"clientSecretExpression": "#[attributes.headers['client_secret']]"
},
"id": null,
"pointcutData": null,
"policyTemplateId": 289307,
"apiVersionId": 15694893,
"groupId": "68ef9520-24e9-4cf2-b2f5-620025690913",
"assetId": "client-id-enforcement",
"assetVersion": "1.2.1"
}
Finally please note that if policies is non-null, all existing policies are deleted and replaced by whatever policies you've defined.
So this JSON will leave your policies as-is:
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"assetId": "my-api",
"assetVersion": "1.0.0"
}
}
but this JSON will delete all policies
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"assetId": "my-api",
"assetVersion": "1.0.0",
"policies": []
}
}
SLA Tiers¶
You can specify what SLA Tiers should be configuration with the following JSON.
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"assetId": "my-api",
"assetVersion": "1.0.0"
"slaTiers": [
{
"name": "Premium",
"description": "Premium level SLA tier",
"autoApprove": false,
"limits": [
{
"visible": true,
"timePeriodInMilliseconds": 1000,
"maximumRequests": 10
}
]
}
]
}
}
Application Client¶
You can automatically provision a client application by adding a client object to your anypoint descriptor
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"client": {
"name": "myclientapp-${organization.lname}-${environment.lname}",
"description": "My Client Application",
"url": "http://myapp"
}
}
If you don't specify the name, it will be automatically generated based on the following pattern:
[app id]-${environment.lname}.
So for example at a minimum you can just specify, UNLESS you've create a "Client Provider" in which case you need at least one accessed API (see below)
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"client": {
}
}
API Access¶
You can specify that the API's client be automatically given access to other APIs by specifying the exchange group id, asset id and version for the APIs it should be granted access. If the API granted access to uses an SLA Tier that disables automatic approval, the approval request will be automatically granted as well.
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"client": {
"access": [
{
"orgId": "68ef9520-24e9-4cf2-b2f5-620025690944",
"groupId": "79238423-7259-8329-dk23-234273984723",
"assetId": "otherapi",
"assetVersion": "1.0.0",
"label": "exp"
}
]
}
}
If orgId is not set it will default to the API's organization, and if groupId is not set it will default to the orgId.
Please note that while historically the group id and the org id have been the same, that is no longer the case with newer versions of the anypoint platform.
You can also specify that existing client applications be granted access to your API using accessedBy (you will
also be able to specify those through parameters when deploying).
{
"$schema": "https://docs.enhanced-mule.com/schemas/emule-application-1.0.schema.json",
"api": {
"assetId": "my-api",
"assetVersion": "1.0.0"
"accessedBy": ["someclient1-${environment.lname}","someclient2-${environment.lname}"]
}
}
Multiple APIs¶
Specifying multiple APIs in the descriptor is planned but not implemented yet. Add a comment to this issue if you need it:
https://gitlab.com/aeontronix/oss/enhanced-mule-tools/issues/1
Properties injection¶
Several properties will be automatically generated and added to the application properties when it's deployed:
anypoint.api.id: The API id generated for the APIanypoint.platform.client_id: The environment platform client idanypoint.platform.client_secret: The environment platform client idanypoint.api.client.id: The client id for the generated application clientanypoint.api.client.secret: The client secret for the generated application client