Re: [Architecture] REST API for Application Template Management
Hi Frank,
On Wed, Apr 1, 2020 at 10:37 PM Frank Leymann wrote:
> Dear Pamoda,
>
>
>- Why do you need both, limitWithoutDefaultQueryParam as well
>as limitQueryParam? Won't limitQueryParam do what we need? (same question
>for other parameters like offset etc)
>- Parameters like sortByQueryParam is not supported in the current
>version (according to the Swagger file). What response do we return if such
>a parameter is passed in the query string: "400 Bad Request" or "501 Not
>Implemented"? Wouldn't it be more convenient for an API user (or reviewer)
>to not document parameters that are not (yet) supported?
>- POST /applications has a JSON document as payload.
>In contrast, POST /applications/import supports an XML file, which is
>passed as a binary file in the payload
> - Is this a Base64 encoded binara? If YES, we should say so.
> Otherwise: I don't understand :-)
> - If XML is still important for us, why doesn't POST /applications
> not support XML as payload too?
>
> So, the underlying observation is that it seems to be strange (to me) to
> invent an *import* API for creating new application from XML documents,
> while a new application is created based on a JSON document via a different
> API. The semantics of the APIs is the same, only the representation of the
> payload is different... Can't we combine the two APIs supporting different
> types of payloads?
>
>
The application import API can be used to create a new application
directly, by uploading an XML representation. But we can't create
applications in the system using the template API. It only gives the
capability to store application templates and we can use these templates in
the UI to auto-fill the fields when the user is creating an application.
IMHO, these two APIs serve two different purposes, entirely.
The import API uses the ApplicationManagementService [1], which has
dedicated XML based methods [2] to import and export an application. So we
had to stick with XML, at least for the time being. But the new templates
API uses the TemplateManager [3] which only required Template objects.
Therefore we were able to use JSON and from the API layer, we convert the
JSON payload to a Template object.
I hope I've answered your queries?
>
>- PUT /applications/import is used to *substitute* an application that
>has been provided by means of an XML document before. But an application
>that has been created based on a JSON document can be (partially) updated
>via PATCH /applications/{applicationId}. Again, the representation of the
>resource determines how it can be manipulated. This seems to be strange (to
>me) and not consistent with the REST paradigm.
>- Is there any documentation about the semantics of the PATCH model
>(ie. what is the language I use to specify what is updated; what if some
>updates can be applied, some others not [i.e. is there any notion of
>"atomicity" of updates])?
>
> Thanks!
>
> Best regards,
> Frank
>
> Regards,
Vihanga.
[1] -
https://github.com/wso2/carbon-identity-framework/blob/master/components/application-mgt/org.wso2.carbon.identity.application.mgt/src/main/java/org/wso2/carbon/identity/application/mgt/ApplicationManagementService.java
[2] -
https://github.com/wso2/carbon-identity-framework/blob/master/components/application-mgt/org.wso2.carbon.identity.application.mgt/src/main/java/org/wso2/carbon/identity/application/mgt/ApplicationManagementService.java#L258
[3] -
https://github.com/wso2/carbon-identity-framework/blob/master/components/template-mgt/org.wso2.carbon.identity.template.mgt/src/main/java/org/wso2/carbon/identity/template/mgt/TemplateManager.java
--
Vihanga Liyanage
Senior 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] REST API for Application Template Management
Dear Pamoda,
- Why do you need both, limitWithoutDefaultQueryParam as well
as limitQueryParam? Won't limitQueryParam do what we need? (same question
for other parameters like offset etc)
- Parameters like sortByQueryParam is not supported in the current
version (according to the Swagger file). What response do we return if such
a parameter is passed in the query string: "400 Bad Request" or "501 Not
Implemented"? Wouldn't it be more convenient for an API user (or reviewer)
to not document parameters that are not (yet) supported?
- POST /applications has a JSON document as payload.
In contrast, POST /applications/import supports an XML file, which is
passed as a binary file in the payload
- Is this a Base64 encoded binara? If YES, we should say so.
Otherwise: I don't understand :-)
- If XML is still important for us, why doesn't POST /applications
not support XML as payload too?
So, the underlying observation is that it seems to be strange (to me) to
invent an *import* API for creating new application from XML documents,
while a new application is created based on a JSON document via a different
API. The semantics of the APIs is the same, only the representation of the
payload is different... Can't we combine the two APIs supporting different
types of payloads?
- PUT /applications/import is used to *substitute* an application that
has been provided by means of an XML document before. But an application
that has been created based on a JSON document can be (partially) updated
via PATCH /applications/{applicationId}. Again, the representation of the
resource determines how it can be manipulated. This seems to be strange (to
me) and not consistent with the REST paradigm.
- Is there any documentation about the semantics of the PATCH model (ie.
what is the language I use to specify what is updated; what if some updates
can be applied, some others not [i.e. is there any notion of "atomicity" of
updates])?
Thanks!
Best regards,
Frank
Am Mi., 1. Apr. 2020 um 16:25 Uhr schrieb Pamoda Wimalasiri :
> Hi all,
>
> We have introduced a set of new REST APIs for managing the application
> templates. These new application template management APIs are added as an
> improvement to the Application Management API. With these APIs, the
> frequently used application configurations can be saved as a template so
> that they can be reused when creating a new application.
>
> Following new endpoints are added for Application Template Management.
>
>- *GET */applications/templates
> - Retrieve all the application templates created for a tenant.
>- *POST* /applications/templates
> - Create a new application template
>- *GET */applications/templates/{template-id}
> - Get the application template information when given the template
> id
>- *PUT* /applications/templates/{template-id}
> - Update an application template when given with the template id
>- *DELETE*/applications/templates/{template-id}
> - Delete the application template with the given template id
>
> The swagger definition of these API can be found here
>
> .[1]
>
> Application Template Management service is implemented using the Template
> Manager OSGi services. The implementation details related to the
> Application Template Management API can be found here
>
> [2].
>
> [1]
> https://app.swaggerhub.com/apis/pamoda/wso-2_identity_server_application_management_rest_api/v1#/Application%20Templates
> [2]
> https://github.com/wso2/identity-api-server/commit/d47979934d852cd47d44f8ece1129da1b8e0f328
>
> Thanks,
> Pamoda
> --
> *Pamoda Wimalasiri | *Senior Software Engineer | WSO2 Inc.
> (m) +94713705814 | (w) +94112145345 | (e) pam...@wso2.com
>
>
> ___
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
[Architecture] REST API for Application Template Management
Hi all,
We have introduced a set of new REST APIs for managing the application
templates. These new application template management APIs are added as an
improvement to the Application Management API. With these APIs, the
frequently used application configurations can be saved as a template so
that they can be reused when creating a new application.
Following new endpoints are added for Application Template Management.
- *GET */applications/templates
- Retrieve all the application templates created for a tenant.
- *POST* /applications/templates
- Create a new application template
- *GET */applications/templates/{template-id}
- Get the application template information when given the template id
- *PUT* /applications/templates/{template-id}
- Update an application template when given with the template id
- *DELETE*/applications/templates/{template-id}
- Delete the application template with the given template id
The swagger definition of these API can be found here
.[1]
Application Template Management service is implemented using the Template
Manager OSGi services. The implementation details related to the
Application Template Management API can be found here
[2].
[1]
https://app.swaggerhub.com/apis/pamoda/wso-2_identity_server_application_management_rest_api/v1#/Application%20Templates
[2]
https://github.com/wso2/identity-api-server/commit/d47979934d852cd47d44f8ece1129da1b8e0f328
Thanks,
Pamoda
--
*Pamoda Wimalasiri | *Senior Software Engineer | WSO2 Inc.
(m) +94713705814 | (w) +94112145345 | (e) pam...@wso2.com
___
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
