Create or update an endpoint

Purpose

Creates an endpoint. An endpoint allows a client to connect to Eclipse Amlen.

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

http://<admin-endpoint-IP:Port>/ima/v1/configuration/

Object configuration data

Provide endpoint object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:


{    
   "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 endpoint 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.

You must specify at least one of the following 3 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.
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.

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".
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.
Enable About Eclipse Amlen panel: 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.

Usage Notes®

Capitalization and double quotation marks must be used as shown.
Each endpoint must have at least one connection policy, and at least one messaging policy.

Related REST Administration APIs

Example

Creates 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/

An example response to the POST method:


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