Re: [Architecture] [IS 5.10.0] Email Templates REST API

[Vihanga Liyanage]

Hi all,

Please find the meeting notes of the discussion below.

Participants: Darshana, Ayesha, Maduranga, Farasath and myself

Notes:

   - Both approaches were discussed for the API designing, considering the
   ease of understanding the API by a third party and the ease of use in terms
   of a developer.
   - Out of the two options, having a dedicated path for locales instead of
   a query param was preferred.
   - The locale of an email template acts as the key to identify that
   particular template, of the respective email template type. This behaviour
   is unique compared to other similar APIs such as challenge questions.
   - To avoid any further confusion on the matter, some of the names used
   were changed and the new API paths are as below.
  - */email/template-types:*
 - GET - Retrieve all email template types with limited information
 of the email templates.
 - POST - Create new email template type with or without email
 templates.
  - */email/template-types/{template-type-id}:*
 - GET - Retrieve the email template type corresponds to the
 template type id.
 - POST - Add a new email template to an existing email template
 type.
 - PUT - Replace all email templates of the respective email
 template type with the newly provided email templates.
 - DELETE - Removes an email template type.
  - */email/template-types/{template-type-id}/templates:*
 - GET - Retrieve the set of locale objects corresponds to the
 template type id.
  - */email/template-types/{template-type-id}/templates/{template-id}:*
 - GET - Retrieves the email template of the provided locale of the
 corresponding email template type id.
 - PUT - Replace the email template identified by the locale, of
 the respective email template type.
 - DELETE - Removes an email template that corresponds to the email
 template type ID and the locale.
  - Email template type object will look as follows.
  - {
"id": "YWNjb3VudGNvbmZpcm1hdGlvbg",
"displayName": "Account Confirmation Template",
"templates": [
  {
"id": "en_US",
"contentType": "text/html",
"subject": "WSO2 - Account Confirmation",
"body": "HTML Body",
"footer": "WSO2 Identity Server Team"
  }
]
  }

I will update the swagger definitions accordingly and update the thread.

Regards,
Vihanga.

On Wed, Oct 2, 2019 at 3:05 PM Vihanga Liyanage  wrote:

> Hi Ayesha,
>
> The above design was suggested considering the fact that an email template
> in a specific email template type can only be identified by its locale.
>
> However, I understand your concern and I've designed a new API definition
> [1] considering your suggestions. I've also sent an invitation [2] to a
> discussion to finalize the design. Since this might affect the timelines of
> the release, appreciate if everyone can participate.
>
> Regards,
> Vihanga.
>
> [1] - https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v2-oas3#/
> [2] - "[Urgent] [Review] Email Templates REST API Refined Swagger."
>
> On Wed, Oct 2, 2019 at 12:59 PM Ayesha Dissanayaka 
> wrote:
>
>> Hi Vihanga,
>>
>>
>> On Tue, Oct 1, 2019 at 10:10 AM Vihanga Liyanage 
>> wrote:
>>
>>> Hi all,
>>>
>>> We're in the process of designing and implementing a REST API for email
>>> templates. This API will cover all the functionalities exposed through the
>>> *I18nEmailMgtConfigService* admin service.
>>> As of now, we've designed the swagger definition [1]
>>>  for the
>>> API and now starting the development. Current API definition has the
>>> following paths.
>>>
>>>- /email/templates:
>>>- GET - Retrieve all email template types with limited information
>>>   of the email templates.
>>>   - POST - Create new email template type with or without email
>>>   templates.
>>>- /email/templates/{email-template-type-id}:
>>>- GET - Retrieve the email template type corresponds to the template
>>>   type id.
>>>   - POST - Add a new email template to an existing email template
>>>   type.
>>>   - PUT - Replace all email templates of the respective email
>>>   template type with the newly provided email templates.
>>>   - DELETE - Removes an email template type.
>>>- /email/templates/{email-template-type-id}/locale:
>>>- GET - Retrieve the set of locale objects corresponds to the
>>>   template type id.
>>>- /email/templates/{email-template-type-id}/locale/{locale-code}:
>>>- GET - Retrieves the email template of the provided locale of the
>>>   corresponding email template type id.
>>>   - PUT - Replace the email template identified by the locale, of
>>>   the respective email template type.
>>>   - DELETE - Removes an email template that 

Re: [Architecture] [IS 5.10.0] Email Templates REST API

[Vihanga Liyanage]

Hi Ayesha,

The above design was suggested considering the fact that an email template
in a specific email template type can only be identified by its locale.

However, I understand your concern and I've designed a new API definition
[1] considering your suggestions. I've also sent an invitation [2] to a
discussion to finalize the design. Since this might affect the timelines of
the release, appreciate if everyone can participate.

Regards,
Vihanga.

[1] - https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v2-oas3#/
[2] - "[Urgent] [Review] Email Templates REST API Refined Swagger."

On Wed, Oct 2, 2019 at 12:59 PM Ayesha Dissanayaka  wrote:

> Hi Vihanga,
>
>
> On Tue, Oct 1, 2019 at 10:10 AM Vihanga Liyanage  wrote:
>
>> Hi all,
>>
>> We're in the process of designing and implementing a REST API for email
>> templates. This API will cover all the functionalities exposed through the
>> *I18nEmailMgtConfigService* admin service.
>> As of now, we've designed the swagger definition [1]
>>  for the API
>> and now starting the development. Current API definition has the following
>> paths.
>>
>>- /email/templates:
>>- GET - Retrieve all email template types with limited information of
>>   the email templates.
>>   - POST - Create new email template type with or without email
>>   templates.
>>- /email/templates/{email-template-type-id}:
>>- GET - Retrieve the email template type corresponds to the template
>>   type id.
>>   - POST - Add a new email template to an existing email template
>>   type.
>>   - PUT - Replace all email templates of the respective email
>>   template type with the newly provided email templates.
>>   - DELETE - Removes an email template type.
>>- /email/templates/{email-template-type-id}/locale:
>>- GET - Retrieve the set of locale objects corresponds to the
>>   template type id.
>>- /email/templates/{email-template-type-id}/locale/{locale-code}:
>>- GET - Retrieves the email template of the provided locale of the
>>   corresponding email template type id.
>>   - PUT - Replace the email template identified by the locale, of
>>   the respective email template type.
>>   - DELETE - Removes an email template that corresponds to the email
>>   template type ID and the locale.
>>
>> IMO, the locale is not a first-class resource in a
> {email-template-type-id} resource, rather it is an attribute if a
> particular email template which qualifies the language. I suggest that
> rather than qualifying it as a path parameter it should be a filtering
> attribute(query parameter) to the GET request. (ex:
> /email/templates/{email-template-type-id}?locale={locale})
>
> For POST and PUT, the locale property is defined in the content. Hence,
> specifying in the path is redundant. (ex:
> /email/templates/{email-template-type-id})
>
> For DELETE, again the locale can be a filtering attribute. If not
> specified, delete all. (ex:
> /email/templates/{email-template-type-id}?locale={locale})
>
> Also, we may remove the *displayName* of the locale from the response as
> the codes used for locale are universal.
>
> "locale": {
>   "code": "en_US",
>   "displayName": "English (United States)"
> }
>
> All your valuable input on this are highly appreciated.
>>
>> Regards,
>> Vihanga.
>>
>> [1] - https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v1#/
>>
>> --
>>
>> Vihanga Liyanage
>>
>> Software Engineer | WS*O₂* Inc.
>>
>> M : +*94710124103* | http://wso2.com
>>
>> [image: http://wso2.com/signature] 
>>
>
>
> --
> *Ayesha Dissanayaka*
> Associate Technical Lead
> WSO2, Inc : http://wso2.com
> 
> 20, Palm grove Avenue, Colombo 3
> E-Mail: aye...@wso2.com 
> Mobile: +94713580922
>


-- 

Vihanga Liyanage

Software Engineer | WS*O₂* Inc.

M : +*94710124103* | http://wso2.com

[image: http://wso2.com/signature] 
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

Re: [Architecture] [IS 5.10.0] Email Templates REST API

[Ayesha Dissanayaka]

Hi Vihanga,


On Tue, Oct 1, 2019 at 10:10 AM Vihanga Liyanage  wrote:

> Hi all,
>
> We're in the process of designing and implementing a REST API for email
> templates. This API will cover all the functionalities exposed through the
> *I18nEmailMgtConfigService* admin service.
> As of now, we've designed the swagger definition [1]
>  for the API
> and now starting the development. Current API definition has the following
> paths.
>
>- /email/templates:
>- GET - Retrieve all email template types with limited information of
>   the email templates.
>   - POST - Create new email template type with or without email
>   templates.
>- /email/templates/{email-template-type-id}:
>- GET - Retrieve the email template type corresponds to the template
>   type id.
>   - POST - Add a new email template to an existing email template
>   type.
>   - PUT - Replace all email templates of the respective email
>   template type with the newly provided email templates.
>   - DELETE - Removes an email template type.
>- /email/templates/{email-template-type-id}/locale:
>- GET - Retrieve the set of locale objects corresponds to the template
>   type id.
>- /email/templates/{email-template-type-id}/locale/{locale-code}:
>- GET - Retrieves the email template of the provided locale of the
>   corresponding email template type id.
>   - PUT - Replace the email template identified by the locale, of the
>   respective email template type.
>   - DELETE - Removes an email template that corresponds to the email
>   template type ID and the locale.
>
> IMO, the locale is not a first-class resource in a
{email-template-type-id} resource, rather it is an attribute if a
particular email template which qualifies the language. I suggest that
rather than qualifying it as a path parameter it should be a filtering
attribute(query parameter) to the GET request. (ex:
/email/templates/{email-template-type-id}?locale={locale})

For POST and PUT, the locale property is defined in the content. Hence,
specifying in the path is redundant. (ex:
/email/templates/{email-template-type-id})

For DELETE, again the locale can be a filtering attribute. If not
specified, delete all. (ex:
/email/templates/{email-template-type-id}?locale={locale})

Also, we may remove the *displayName* of the locale from the response as
the codes used for locale are universal.

"locale": {
  "code": "en_US",
  "displayName": "English (United States)"
}

All your valuable input on this are highly appreciated.
>
> Regards,
> Vihanga.
>
> [1] - https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v1#/
>
> --
>
> Vihanga Liyanage
>
> Software Engineer | WS*O₂* Inc.
>
> M : +*94710124103* | http://wso2.com
>
> [image: http://wso2.com/signature] 
>


-- 
*Ayesha Dissanayaka*
Associate Technical Lead
WSO2, Inc : http://wso2.com

20, Palm grove Avenue, Colombo 3
E-Mail: aye...@wso2.com 
Mobile: +94713580922
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture

[Architecture] [IS 5.10.0] Email Templates REST API

[Vihanga Liyanage]

Hi all,

We're in the process of designing and implementing a REST API for email
templates. This API will cover all the functionalities exposed through the
*I18nEmailMgtConfigService* admin service.
As of now, we've designed the swagger definition [1]
 for the API
and now starting the development. Current API definition has the following
paths.

   - /email/templates:
   - GET - Retrieve all email template types with limited information of
  the email templates.
  - POST - Create new email template type with or without email
  templates.
   - /email/templates/{email-template-type-id}:
   - GET - Retrieve the email template type corresponds to the template
  type id.
  - POST - Add a new email template to an existing email template type.
  - PUT - Replace all email templates of the respective email template
  type with the newly provided email templates.
  - DELETE - Removes an email template type.
   - /email/templates/{email-template-type-id}/locale:
   - GET - Retrieve the set of locale objects corresponds to the template
  type id.
   - /email/templates/{email-template-type-id}/locale/{locale-code}:
   - GET - Retrieves the email template of the provided locale of the
  corresponding email template type id.
  - PUT - Replace the email template identified by the locale, of the
  respective email template type.
  - DELETE - Removes an email template that corresponds to the email
  template type ID and the locale.

All your valuable input on this are highly appreciated.

Regards,
Vihanga.

[1] - https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v1#/

-- 

Vihanga Liyanage

Software Engineer | WS*O₂* Inc.

M : +*94710124103* | http://wso2.com

[image: http://wso2.com/signature] 
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture