[
https://issues.apache.org/jira/browse/QPID-6948?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16148718#comment-16148718
]
Lorenz Quack edited comment on QPID-6948 at 8/31/17 9:34 AM:
-------------------------------------------------------------
We should consider creating an [OpenAPI 3.0.0
document|https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md]
describing the different versions of our API.
I think this would provide the following benefits (non exhaustive and in no
particular order):
* make it easier for clients to consume our API
* define a contract. Currently it is easy for us to unintentionally change the
API without realizing. If the WMC does not break we might not know. With an
OpenAPI document we at least have the possibility to detect the discrepancy.
* adding to the previous point: Ideally this would allow us to generate
automated REST tests. Some interesting links regarding this: [apigee blog
entry|https://apigee.com/about/blog/developer/swagger-test-templates-test-your-apis],
[assertible blog
entry|https://assertible.com/blog/using-swagger-openapi-to-continuously-test-your-api-from-a-ci-pipeline],
[github project (WIP): OpenAPI Test
Templates|https://github.com/noahdietz/oatts], [Interesting mail
discussion|https://groups.google.com/forum/#!topic/swagger-swaggersocket/9AQ2k9OtHWM]
While this does not help with the actual implementation of the compatibility
layer it does help with the testability and general quality of our API.
was (Author: lorenz.quack):
We should consider creating an [OpenAPI 3.0.0
document|https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md]
describing the different versions of our API.
I think this would provide the following benefits (non exhaustive and in no
particular order):
* make it easier for clients to consume our API
* define a contract. Currently it is easy for us to unintentionally change the
API without realizing. If the WMC does not break we might not know. With an
OpenAPI document we at least have the possibility to detect the discrepancy.
* adding to the previous point: Ideally this would allow us to generate
automated REST tests. Some interesting links regarding this: [apigee blog
entry|https://apigee.com/about/blog/developer/swagger-test-templates-test-your-apis],
[assertible blog
entry|https://assertible.com/blog/using-swagger-openapi-to-continuously-test-your-api-from-a-ci-pipeline],
[github project (WIP): OpenAPI Test
Templates|https://github.com/noahdietz/oatts]
While this does not help with the actual implementation of the compatibility
layer it does help with the testability and general quality of our API.
> Introduce REST API compatibility layer
> --------------------------------------
>
> Key: QPID-6948
> URL: https://issues.apache.org/jira/browse/QPID-6948
> Project: Qpid
> Issue Type: Improvement
> Components: Java Broker
> Reporter: Keith Wall
>
> Make the REST API backwardly compatibility with model as used by 0.32.
> In general the compatibility layer should:
> For GET:
> * attributes that are removed should be simulated (e.g. defaultVirtualHost)
> * new attributes/new types don't need to be hidden
> For POST/PUT:
> * on creation, new mandatory attributes should be given sensible defaults
> * removed operations should be supported perhaps by rewriting the request in
> terms of new operations.
> When the model changes structurally, the compatibility layer should present
> the old model.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
