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 <viha...@wso2.com> 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 <aye...@wso2.com>
> wrote:
>
>> Hi Vihanga,
>>
>>
>> On Tue, Oct 1, 2019 at 10:10 AM Vihanga Liyanage <viha...@wso2.com>
>> 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]
>>> <https://app.swaggerhub.com/apis/vihanga/EmailTemplate/v1#/> 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] <http://wso2.com/signature>
>>>
>>
>>
>> --
>> *Ayesha Dissanayaka*
>> Associate Technical Lead
>> WSO2, Inc : http://wso2.com
>> <http://www.google.com/url?q=http%3A%2F%2Fwso2.com&sa=D&sntz=1&usg=AFQjCNEZvyc0uMD1HhBaEGCBxs6e9fBObg>
>> 20, Palm grove Avenue, Colombo 3
>> E-Mail: aye...@wso2.com <ayshsa...@gmail.com>
>> Mobile: +94713580922
>>
>
>
> --
>
> Vihanga Liyanage
>
> Software Engineer | WS*O₂* Inc.
>
> M : +*94710124103* | http://wso2.com
>
> [image: http://wso2.com/signature] <http://wso2.com/signature>
>
--
Vihanga Liyanage
Software Engineer | WS*O₂* Inc.
M : +*94710124103* | http://wso2.com
[image: http://wso2.com/signature] <http://wso2.com/signature>
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
