Hi Asitha/All,
The paths overall look good to me too and +1 to the Harsha's suggestion on
pagination.
I have a small suggestion regarding below concern Asitha has mentioned:
I have few concerns regarding deleting bindings. There is no unique key for
> the binding hence I was thinking of something like following for the delete
> binding (combination of routing key and queue name is unique)
> */exchanges/{exchangeName}/bindings/{routingKey}/{queueName}*
> What about using something like
> */exchanges/{exchangeName}/bindings?routingKey=myTopic&queueName=tmp_1234 *for
> the delete? Can we consider a URI with query params as a unique resource?
>
Shall we introduce a new ID to identify binding? It can be a unique UUID. This
is the approach we have been using in APIM APIs.
When we create a new binding, the response will include the unique UUID.
Eg:
*Request:*
POST /exchanges/*exchange1*/bindings
{
"routingKey": "routingPattern",
"queueName": "myQueue",
"filterExpression": "MessageId = 12345"
}
*Response:*
HTTP/1.1 201 Created
Location: *https://localhost:9292/admin/1.0
<https://localhost:9292/admin/1.0>*/exchanges/*exchange1*/bindings/
*4a349d47-12fa-490c-bb06-d90610a4897d*
{
* "id" : "4a349d47-12fa-490c-bb06-d90610a4897d"*
"routingKey": "routingPattern",
"queueName": "myQueue",
"filterExpression": "MessageId = 12345"
}
We can use this ID for next operations with it.
Eg:
GET *https://localhost:9292/admin/1.0 <https://localhost:9292/admin/1.0>*/
exchanges/*exchange1*/bindings/*4a349d47-12fa-490c-bb06-d90610a4897d*
DELETE *https://localhost:9292/admin/1.0 <https://localhost:9292/admin/1.0>*
/exchanges/*exchange1*/bindings/*4a349d47-12fa-490c-bb06-d90610a4897d*
Also binding list can include each bindings IDs:
eg:
GET /exchanges/*exchange1*/bindings?offset=20&limit=10
{
"count": 10,
"list": [ {
* "id" : "4a349d47-12fa-490c-bb06-d90610a4897d"*
"routingKey": "routingPattern",
"queueName": "myQueue",
"filterExpression": "MessageId = 12345"
},
{
* "id" : "d6cf5769-33a1-48e7-b9fd-3db8580292e0"*
"routingKey": "routingPattern2",
"queueName": "myQueue2",
"filterExpression": "MessageId = 123456789"
},
...
...
],
"pagination": {
"total": 134,
"offset": 20,
"limit": 10,
"next": "/exchanges/*exchange1*/bindings?offset=30&limit=10",
"previous": "/exchanges/*exchange1*/bindings?offset=10&limit=10"
}
}
Thanks!
On Mon, Jan 15, 2018 at 10:49 PM, Harsha Kumara <[email protected]> wrote:
>
>
> On Fri, Jan 12, 2018 at 9:35 AM, Asitha Nanayakkara <[email protected]>
> wrote:
>
>> Hi all,
>>
>> Taking all the concerns discussed in to account I did some updates on the
>> design.
>>
>> With this design, I'll be exposing the exchanges, bindings, queues, and
>> consumers. This is to avoid confusion in coming up with a design to expose
>> topics (pub-sub pattern) as a first-class citizen (Since it is another
>> exchange within the broker).
>>
>> Following is the updated design
>>
>>
>> Base path /broker/v.1.0
>>
>>
>>
>>
>>
>>
>>
>> Queues
>>
>>
>> 5 Create Queue/Topic POST /queues/ { "name": "queueName", "durable":
>> true, "autoDelete": false }
>> 6 List Queues/Topics GET /queues
>> 7 Get Queue Details GET /queues/{queueName}
>> 8 Delete Queue DELETE /queues/{queueName}
>>
>>
>>
>>
>>
>>
>> Subscriptions for a queue or topic
>>
>>
>> 9 List subscriptions for a destination GET /queues/{queueName}/consumers
>> 10 Get subscriber details GET /queues/{queueName}/consumers/{consumerTag}
>> 11 Close subscriber DELETE /queues/{queueName}/consumers/{consumerTag}
>>
>>
>>
>>
>>
>>
>> Exchanges
>>
>>
>> 1 Create Exchange POST /exchanges { "name": "exchangeName", "type":
>> "amq.direct", "durable": true }
>> 2 Get All exchanges GET /exchanges
>> 3 Get Exchange GET /exchanges/{exchangeName}
>> 4 Delete Exchange DELETE /exchanges/{exchangeName}
>>
>>
>>
>>
>>
>>
>> Bindings
>>
>>
>>
>> List bindings for exchange GET /exchanges/{exchangeName}/bindings
>>
>> Add binding POST /exchanges/{exchangeName}/bindings {"routingKey":
>> "routingPattern", "queueName": "myQueue", "filterExpression": "MessageId =
>> 12345"}
>>
>> Delete binding DELETE /exchanges/{exchangeName}/bind
>> ings/{routingKey}/{queueName}
>>
>>
>>
>>
>>
>>
>> I have few concerns regarding deleting bindings. There is no unique key
>> for the binding hence I was thinking of something like following for the
>> delete binding (combination of routing key and queue name is unique)
>> */exchanges/{exchangeName}/bindings/{routingKey}/{queueName}*
>>
>> What about using something like
>> */exchanges/{exchangeName}/bindings?routingKey=myTopic&queueName=tmp_1234
>> *for the delete? Can we consider a URI with query params as a unique
>> resource?
>>
>> I have attached the swagger file for the API as well.
>>
> Attached swagger is looks fine. You will need to add the details about
> authetication schemes in to the swagger itself which will be useful. Also
> the results which returns lists such as queues will be required to have
> pagination. In APIM we are using separate pagination context in response as
> follow.
>
> {
> "count": 2,
> ...
> ...
> "pagination": {
> "total": 4,
> "offset": 0,
> "limit": 2
>
> }
>
> }
>>
>>
>> Regards,
>> Asitha
>>
>>
>> On Thu, Jan 11, 2018 at 8:36 AM, Asanka Abeyweera <[email protected]>
>> wrote:
>>
>>> Hi Asitha,
>>>
>>> I think it is better to say queues rather than destinations since the
>>> actions mean different things in queues and topics. For example,
>>>
>>> - Create
>>> - Queues - we can create the queue in broker core. This will be
>>> useful in assigning permissions
>>> - Topics - We can't do anything at broker code. Corresponding
>>> queues will depend on the subscription id if durable, random name if
>>> non
>>> durable.
>>> - Search
>>> - Queues - we can return queues matching the search criteria
>>> - Topics - It's hard to decide what to return since their can be
>>> unlimited number of options.
>>> - Delete
>>> - Queues - we can delete the specified queues
>>> - Topics - Again bit ambiguous what to delete. Maybe we can go
>>> through the matching bindings and delete the matching queues. My
>>> opinion is
>>> we should not do such a thing.
>>>
>>> Addtionally when we are desiging the REST API better if we dont expose
>>> functionalities that we are expecting to expose through the HTTP transport.
>>> I think the main objective in the first iteration should be to assist the
>>> users in debugging issues. Some information that a user might need is,
>>>
>>> - Queue list
>>> - Subscriptions for a given queue
>>> - Queue details - number messages etc
>>> - Message details
>>> - Permission details
>>> - Binding details of a queue. Will be very useful for topic
>>> scenarios.
>>>
>>>
>>> On Thu, Jan 11, 2018 at 12:41 AM, Eranda Rajapakshe <[email protected]>
>>> wrote:
>>>
>>>> Hi Asitha,
>>>>
>>>> Thanks for the explanation.
>>>>
>>>> On Wed, Jan 10, 2018 at 10:29 PM, Asitha Nanayakkara <[email protected]>
>>>> wrote:
>>>>
>>>>> Hi Eranda,
>>>>>
>>>>>
>>>>> On Wed, Jan 10, 2018 at 6:47 PM, Eranda Rajapakshe <[email protected]>
>>>>> wrote:
>>>>>
>>>>>> Hi all,
>>>>>>
>>>>>> Small addition to the Malintha's suggestion, I think a binding should
>>>>>> be a 3-tuple element <exchange-name, queue-name, routing-key>
>>>>>>
>>>>> For Bindings, we'll be using queue-name, routing-key, and filters.
>>>>> Exchange name can be inferred since we define bindings for a given
>>>>> exchange.
>>>>>
>>>> +1
>>>>
>>>>>
>>>>>> Also, is it correct to use the term "destination" to generalize
>>>>>> queues and topics? AFAIK it's coming from the JMS world.
>>>>>>
>>>>> Yes, If we are going with a separate path for queues, outside
>>>>> /exchanges, we can have something like /queues. Used destinations to avoid
>>>>> the confusion with queues and topics.
>>>>>
>>>> Understood. +1
>>>> I think its better to use the term "queue" if we are going to expose
>>>> this as a AMQP broker.
>>>>
>>>>>
>>>>>> Thanks,
>>>>>>
>>>>>> On Wed, Jan 10, 2018 at 6:29 PM, Asitha Nanayakkara <[email protected]>
>>>>>> wrote:
>>>>>>
>>>>>>> Hi all,
>>>>>>>
>>>>>>> @Eranda: Thanks for pointing out the concern. We will be able to get
>>>>>>> over this concern by way of following the approach suggested by
>>>>>>> Malintha.
>>>>>>>
>>>>>>> @Malintha; Only concern I have with exposing GET /destinations is,
>>>>>>> we will expose all the queues, including temporary queues created for
>>>>>>> topics. Maybe we might be able to get over this by way of using filters.
>>>>>>>
>>>>>>> @Sanjeewa: We are planning to write this admin service using MSF4J
>>>>>>> and we are exposing this to do administrative tasks on the broker.
>>>>>>> Eventually the broker UI will use these servises as well. I will work on
>>>>>>> creating the swagger definitions based on these suggessions.
>>>>>>>
>>>>>>> Regards,
>>>>>>> Asitha
>>>>>>>
>>>>>>> On Wed, Jan 10, 2018 at 6:10 PM, Malintha Amarasinghe <
>>>>>>> [email protected]> wrote:
>>>>>>>
>>>>>>>> Hi all,
>>>>>>>>
>>>>>>>> A suggestion for Eranda's concern, for that I think we need to
>>>>>>>> remove the "exchanges" from the destinations APIs.
>>>>>>>>
>>>>>>>> One possible solution is:
>>>>>>>>
>>>>>>>> *Create Queue/Topic*
>>>>>>>> POST /destinations { "name": "queueName", "durable": true,
>>>>>>>> "autoDelete": false }
>>>>>>>>
>>>>>>>> *List Queues/Topics *
>>>>>>>> GET /destinations
>>>>>>>>
>>>>>>>> *Get Queue Details *
>>>>>>>> GET /destinations/{destinationName}
>>>>>>>>
>>>>>>>> *Delete Queue *
>>>>>>>> DELETE /destinations/{destinationName}
>>>>>>>>
>>>>>>>> *New APIs for adding/retrieving bindings:*
>>>>>>>>
>>>>>>>> *Add a new binding: (not sure about the name "binding" is
>>>>>>>> appropriate)*
>>>>>>>> POST /bindings
>>>>>>>> {
>>>>>>>> "exchangeName" : "exchange1",
>>>>>>>> "destinationName" : "destination1"
>>>>>>>> }
>>>>>>>>
>>>>>>>> *Get bindings for a particular exchange:*
>>>>>>>> GET /bindings?exchangeName="exchange1" => Provides a list of
>>>>>>>> bindings for the particular exchange
>>>>>>>>
>>>>>>>> During a discussion, Asitha mentioned about default exchange; If
>>>>>>>> exchangeName is not provided can we use it as its default value?
>>>>>>>>
>>>>>>>> WDYT?
>>>>>>>>
>>>>>>>> Thanks!
>>>>>>>>
>>>>>>>>
>>>>>>>> On Wed, Jan 10, 2018 at 5:59 PM, Sanjeewa Malalgoda <
>>>>>>>> [email protected]> wrote:
>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Wed, Jan 10, 2018 at 5:40 PM, Asitha Nanayakkara <
>>>>>>>>> [email protected]> wrote:
>>>>>>>>>
>>>>>>>>>> Adding Harshak, Sanjeewa and Malinthaa
>>>>>>>>>>
>>>>>>>>>> On Wed, Jan 10, 2018 at 5:37 PM, Asitha Nanayakkara <
>>>>>>>>>> [email protected]> wrote:
>>>>>>>>>>
>>>>>>>>>>> Hi all,
>>>>>>>>>>>
>>>>>>>>>>> In the new message broker implementation we are implementing
>>>>>>>>>>> broker semantics based on AMQP 0.9.1 specification.
>>>>>>>>>>>
>>>>>>>>>>> From an administrative operations perspective, we have
>>>>>>>>>>> identified following resources to be exposed through restful web
>>>>>>>>>>> services.
>>>>>>>>>>>
>>>>>>>>>>> - exchanges
>>>>>>>>>>> - queues
>>>>>>>>>>> - topics
>>>>>>>>>>> - consumers
>>>>>>>>>>>
>>>>>>>>>>> There are currently two types of exchange. Namely,
>>>>>>>>>>>
>>>>>>>>>>> - direct exchange - relates to mostly known queue scenarios
>>>>>>>>>>> - topic exchange - relates to topic scenarios (pub-sub
>>>>>>>>>>> pattern)
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> *Queues and topics*
>>>>>>>>>>>
>>>>>>>>>>> Within the broker, there are only queues. These queues are bound
>>>>>>>>>>> to direct and topic exchanges. Depending on the bound exchange we
>>>>>>>>>>> perceive
>>>>>>>>>>> them as either pub-sub pattern or queue pattern.
>>>>>>>>>>> Therefore within the Admin API's we refer to either a queue or a
>>>>>>>>>>> topic as a *destination.*
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> *Consumers*
>>>>>>>>>>>
>>>>>>>>>>> For each internal queue (a destination) there will be consumers.
>>>>>>>>>>> Messages are delivered to consumers in round robin manner.
>>>>>>>>>>>
>>>>>>>>>>> In topic scenario (pub-sub pattern) topic exchange will bind a
>>>>>>>>>>> separate queue (a destination) per each consumer with the same
>>>>>>>>>>> topic name.
>>>>>>>>>>> When a message is published it will get delivered to the set of
>>>>>>>>>>> queues with
>>>>>>>>>>> the matching topic and then to the relevant consumers on those
>>>>>>>>>>> queues
>>>>>>>>>>>
>>>>>>>>>>> Considering the above broker semantics we have come up with the
>>>>>>>>>>> following Admin API design for the broker
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> Base path /broker/v.1.0
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> *Exchanges*
>>>>>>>>>>> *Method*
>>>>>>>>>>> *Path*
>>>>>>>>>>> *Payload*
>>>>>>>>>>> 1 Create Exchange POST /exchanges { "name": "exchangeName",
>>>>>>>>>>> "type": "amq.direct", "durable": true }
>>>>>>>>>>> 2 Get All exchanges GET /exchanges
>>>>>>>>>>> 3 Get Exchange GET /exchanges/{exchangeName}
>>>>>>>>>>> 4 Delete Exchange DELETE /exchanges/{exchangeName}
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> *Destinations (Queues/Topics)*
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> 5 Create Queue/Topic POST /exchanges/{exchangeName}/destinations {
>>>>>>>>>>> "name": "queueName", "durable": true, "autoDelete": false }
>>>>>>>>>>> 6 List Queues/Topics GET /exchanges/{exchangeName}/destinations
>>>>>>>>>>> 7 Get Queue Details GET /exchanges/{exchangeName}/dest
>>>>>>>>>>> inations/{destinationName}
>>>>>>>>>>> 8 Delete Queue DELETE /exchanges/{exchangeName}/dest
>>>>>>>>>>> inations/{destinationName}
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> *Consumers (for a queue or topic)*
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> 9 List subscriptions for a destination GET
>>>>>>>>>>> /exchanges/{exchangeName}/destinations/{destinationName}/con
>>>>>>>>>>> sumers
>>>>>>>>>>> 10 Get subscriber details GET /exchanges/{exchangeName}/dest
>>>>>>>>>>> inations/{destinationName}/consumers/{consumerTag}
>>>>>>>>>>> 11 Close subscriber DELETE /exchanges/{exchangeName}/dest
>>>>>>>>>>> inations/{destinationName}/consumers/{consumerTag}
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> When retrieving a set of exchanges, destinations or consumers we
>>>>>>>>>>> will be able to filter the result set by way of using query
>>>>>>>>>>> parameters.
>>>>>>>>>>>
>>>>>>>>>> This API looks good and followed REST nature. I assume exchange
>>>>>>>>> name, destination name, consumer tag etc are unique. Then only we can
>>>>>>>>> build
>>>>>>>>> above mentioned resource model.
>>>>>>>>> Also do we need to let users to check the possibility of creating
>>>>>>>>> exchange, destination or consumer tag before we create it. Then we
>>>>>>>>> might
>>>>>>>>> need http head method as well.
>>>>>>>>> If you need to update que details then you have to use put as
>>>>>>>>> well. Ex: enable/disable auto delete after we create it first time.
>>>>>>>>> Also lets define proper response codes as well(201 to created, 202
>>>>>>>>> accepted etc).
>>>>>>>>>
>>>>>>>>> What is the plan to expose this API to outside? Is it MSF4J? If
>>>>>>>>> that is the case you can start with swagger definition and move
>>>>>>>>> forward.
>>>>>>>>>
>>>>>>>>> Thanks,
>>>>>>>>> sanjeewa.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>>> Regards,
>>>>>>>>>>> Asitha
>>>>>>>>>>>
>>>>>>>>>>> --
>>>>>>>>>>> *Asitha Nanayakkara* <http://asitha.github.io/>
>>>>>>>>>>> Associate Technical Lead
>>>>>>>>>>> WSO2, Inc. <http://wso2.com/>
>>>>>>>>>>> Mob: +94 77 853 0682 <+94%2077%20853%200682>
>>>>>>>>>>> [image: https://wso2.com/signature] <https://wso2.com/signature>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> --
>>>>>>>>>> *Asitha Nanayakkara* <http://asitha.github.io/>
>>>>>>>>>> Associate Technical Lead
>>>>>>>>>> WSO2, Inc. <http://wso2.com/>
>>>>>>>>>> Mob: +94 77 853 0682 <077%20853%200682>
>>>>>>>>>> [image: https://wso2.com/signature] <https://wso2.com/signature>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> --
>>>>>>>>>
>>>>>>>>> *Sanjeewa Malalgoda*
>>>>>>>>> WSO2 Inc.
>>>>>>>>> Mobile : +94713068779 <+94%2071%20306%208779>
>>>>>>>>>
>>>>>>>>> <http://sanjeewamalalgoda.blogspot.com/>blog
>>>>>>>>> :http://sanjeewamalalgoda.blogspot.com/
>>>>>>>>> <http://sanjeewamalalgoda.blogspot.com/>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Malintha Amarasinghe
>>>>>>>> *WSO2, Inc. - lean | enterprise | middleware*
>>>>>>>> http://wso2.com/
>>>>>>>>
>>>>>>>> Mobile : +94 712383306 <+94%2071%20238%203306>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> *Asitha Nanayakkara* <http://asitha.github.io/>
>>>>>>> Associate Technical Lead
>>>>>>> WSO2, Inc. <http://wso2.com/>
>>>>>>> Mob: +94 77 853 0682 <+94%2077%20853%200682>
>>>>>>> [image: https://wso2.com/signature] <https://wso2.com/signature>
>>>>>>>
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Architecture mailing list
>>>>>>> [email protected]
>>>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> *Eranda Rajapakshe*
>>>>>> Software Engineer
>>>>>> WSO2 Inc.
>>>>>> Mobile : +94784822608
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> *Asitha Nanayakkara* <http://asitha.github.io/>
>>>>> Associate Technical Lead
>>>>> WSO2, Inc. <http://wso2.com/>
>>>>> Mob: +94 77 853 0682 <+94%2077%20853%200682>
>>>>> [image: https://wso2.com/signature] <https://wso2.com/signature>
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> *Eranda Rajapakshe*
>>>> Software Engineer
>>>> WSO2 Inc.
>>>> Mobile : +94784822608
>>>>
>>>> _______________________________________________
>>>> Architecture mailing list
>>>> [email protected]
>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>>
>>>>
>>>
>>>
>>> --
>>> Asanka Abeyweera
>>> Associate Technical Lead
>>> WSO2 Inc.
>>>
>>> Phone: +94 712228648 <+94%2071%20222%208648>
>>> Blog: a5anka.github.io
>>>
>>> <https://wso2.com/signature>
>>>
>>
>>
>>
>> --
>> *Asitha Nanayakkara* <http://asitha.github.io/>
>> Associate Technical Lead
>> WSO2, Inc. <http://wso2.com/>
>> Mob: +94 77 853 0682 <+94%2077%20853%200682>
>> [image: https://wso2.com/signature] <https://wso2.com/signature>
>>
>>
>> _______________________________________________
>> Architecture mailing list
>> [email protected]
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
>
> --
> Harsha Kumara
> Software Engineer, WSO2 Inc.
> Mobile: +94775505618 <+94%2077%20550%205618>
> Blog:harshcreationz.blogspot.com
>
> _______________________________________________
> Architecture mailing list
> [email protected]
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>
--
Malintha Amarasinghe
*WSO2, Inc. - lean | enterprise | middleware*
http://wso2.com/
Mobile : +94 712383306 <+94%2071%20238%203306>
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
