[ 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