Creating and updating an endpoint by using REST Administration APIs

System administrators can create and update endpoints by using REST Administration APIs.

Ensure that the following message hub creation tasks are complete:

Create a message hub.
Create connection policies.
Create messaging policy type. There are three types of messaging policy - topic policy, queue policy, and subscription policy.

You can create an endpoint or update an existing by using a REST Administration API, or by using the Amlen WebUI. For more information about using the Amlen WebUI to create an endpoint, see Configuring message hubs by using the Amlen WebUI.

For more information about the components you must specify to create an endpoint, including naming restrictions, see Configuring message hubs.

To create or update an endpoint, use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

http://<admin-endpoint-IP:Port>/ima/v1/configuration/
Provide Endpoint object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.
```
{    
   "Endpoint": {
     "<NameOfEndpoint>": {
       "Description": "string",
       "Port": integer,
       "Interface": "string",
       "Protocol": "string",
       "ConnectionPolicies": "string",
       "TopicPolicies": "string",
       "QueuePolicies": "string",
       "SubscriptionPolicies":  "string", 
       "MaxMessageSize": "string",
       "MessageHub": "string",
       "SecurityProfile": "string",
       "Enabled": true|false,
       "MaxSendSize": integer,
       "BatchMessages": true|false,
       "EnableAbout": true|false
     }
   }
}
```
Where:

NameOfEndpoint

Required.

Specifies the name of the endpoint.

The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:
! # $ % & ' ( ) * + - . / : ; < > ? @

The maximum length of the name is 256 characters.

After the topic policy is created, you cannot change this name.

Description

Optional.

Specifies a description for the endpoint.

If you do not want a description, omit "Description":"description".

Port

Required if you are creating an endpoint.

Specifies the port that clients connect to.

The port number must be in the range 1 - 32767, 61001 - 65535.

Interface

Required if you are creating an endpoint.

Specifies one, or all, of the available Eclipse Amlen IP addresses for the client to connect to.

You can use the value all to specify all available IP addresses.

If you are using Amazon Elastic Cloud Compute (Amazon EC2), ensure that the address that you specify for the endpoint is an Amazon EC2 private IP address that is associated with an Amazon EC2 public elastic IP address.

Protocol

Required if you are creating an endpoint.

Specifies the protocols that the clients can use to connect to the endpoint.

You can choose from JMS and MQTT protocols. If there are any protocol plug-ins installed on the Eclipse Amlen server, you can specify these as well.

To specify more than one value, separate each value with a comma.

To select all protocols, specify All.

ConnectionPolicies

Required if you are creating an endpoint.

Specifies the connection policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.

When Eclipse Amlen checks whether a client is authorized to connect, each connection policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all connection policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.

MaxMessageSize

Optional.

Specifies the maximum size, in bytes, KB or MB, that a message can be when sent to Eclipse Amlen through this endpoint.

The value must be in the range 1 KB - 262144 KB.

The value can include a KB or MB suffix. If no suffix is used, the value is in bytes, in which case the range is 1024 - 268435456.

The default value is 1024 KB.

MessageHub

Required if you are creating an endpoint.

Specifies the message hub that the endpoint belongs to. The message hub must exist.

SecurityProfile

Optional.

Specifies the security profile to be applied to the endpoint. The security profile must exist.

If you do not want to specify a security profile, omit "SecurityProfile":"secProfile".

To remove the current value of security profile, set SecurityProfile to "" in the REST API POST payload.

Enabled: true|false

Required if you are creating an endpoint.

Specifies whether the endpoint is enabled (true) or disabled (false).

MaxSendSize

Optional.

Specifies the maximum size, in bytes, that part of a message can be when it is sent.

The value must be in the range 128 - 65536.

You might want to use this option in environments where resource-constrained devices are used; set a low value for MaxSendSize, for example 256 bytes, and disable the batching of messages by setting BatchMessages to false.

The default value is 16384 bytes.

BatchMessages: true|false

Optional.

Specifies whether messages can be sent in batches (true) or must be sent singly (false). If BatchMessages is false and the size of the message is less than the value specified for MaxSendSize, the message is sent singly. If the size of the message is greater than the value specified for MaxSendSize, the message is sent in multiple fragments; if BatchMessages is false, fragments of different messages cannot be sent in a single send operation.

You might want to set BatchMessages to false in environments where resource-constrained devices are used to ensure that single messages are sent; ensure that you also set a low value for MaxSendSize, for example 256 bytes.

The default value is true.

EnableAbout: true|false

Optional.

Specifies whether the About Eclipse Amlen panel for this endpoint can be reached.

The default value is false which means that the panel for this endpoint cannot be reached.

In production environments, it is best practice to specify a value of false.

You must specify at least one of the following three messaging policy types:

TopicPolicies

Specifies the topic policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.

When Eclipse Amlen checks whether a client is authorized to perform topic messaging actions, each topic policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all topic policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.

SubscriptionPolicies

Specifies the subscription policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.

When Eclipse Amlen checks whether a client is authorized to perform subscription messaging actions, each subscription policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all subscription policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.

If you are using MQTT global-shared subscriptions, you must also specify a topic policy.

QueuePolicies

Specifies the queue policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.

When Eclipse Amlen checks whether a client is authorized to perform queue messaging actions, each queue policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all queue policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.

The following example shows a POST method to create an endpoint called "MyEndpoint" by using cURL:


curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{   
            "Endpoint":  { 
               "MyEndpoint": {
                 "Port": 16102,            
                 "Enabled": false,
                 "Protocol": "All",            
                 "Interface": "All",           
                 "ConnectionPolicies": "MyConnectionPolicy",   
                 "TopicPolicies": "MyTopicPolicy", 
                 "MaxMessageSize": "4096KB",
                 "MessageHub": "MyHub",            
                 "Description": "Unsecured endpoint for demonstration use only."
            }
        }
    }
  '  \
http://127.0.0.1:9089/ima/v1/configuration/

The following example shows an example response to the POST method:


{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}