REST API first pass at Swagger spec
Attached is a first pass at a Swagger spec for the REST API.
You can find out about Swagger at http://swagger.io
The Swagger spec that I am working on is attached to this message or can be found here: http://www.mailripper.com/api-docs.json
If you want to see the attached spec in action against the Mailman REST API, go to http://www.mailripper.com/swagger-ui/index.html
Give it a try at http://www.mailripper.com/swagger-ui/index.html - you are welcome to change anything, it’s a test Mailman server and you can add or delete anything - nothing you do will be a problem.
There’s still a fair bit to do to finalise this but most of the API queries are working - enough for you to see how it works.
Any comments or feedback welcome.
as
Andrew Stuart writes:
Attached is a first pass at a Swagger spec for the REST API.
You can find out about Swagger at http://swagger.io
tmc;wr[1] Please explain briefly what Swagger is and why you're using it rather than some similar product. Two lines is enough. I have ZERO intention of paying attention to what you're doing; my technical plate is full, and Barry's the boss anyway. But if some new person or a GSoC student seems to have an interest in "that kind of thing" I'd like to know enough to say "go talk to Andrew".
Footnotes: [1] Too many clicks; won't read.
The Swagger spec defines a way to document the methods, properties and return values of a REST API using JSON, and also provides a front end user interface to turn that JSON into a functioning user interface to directly query the API. There seems to be a few choices for documentation REST APIs at the moment (http://apiary.io & http://www.mashery.com/product/io-docs) but Swagger appears to have the industry momentum.
I’ve put together a Swagger spec mainly because I’ve experienced enough pain with REST APIs in the past to know that development goes much, much more smoothly when you have a single place that shows all the available API methods, their parameters and return values, ideally live so you can see it working. Instead of digging through source code and written documentation to find how the REST API works, it’s all right there in front of you.
Once the REST API is documented in JSON, a range of things become possible including writing tests, command lines interfaces, clients and servers that “build themselves” to a greater or lesser extent directly from the JSON REST API spec.
Sorry, that was five long lines :-)
On 11 Jan 2015, at 4:23 pm, Stephen J. Turnbull <stephen@xemacs.org> wrote:
Andrew Stuart writes:
Attached is a first pass at a Swagger spec for the REST API.
You can find out about Swagger at http://swagger.io
tmc;wr[1] Please explain briefly what Swagger is and why you're using it rather than some similar product. Two lines is enough. I have ZERO intention of paying attention to what you're doing; my technical plate is full, and Barry's the boss anyway. But if some new person or a GSoC student seems to have an interest in "that kind of thing" I'd like to know enough to say "go talk to Andrew".
Footnotes: [1] Too many clicks; won't read.
On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote:
It looks interesting. I have a little experience with WADL with the Launchpad API. There was a lot of infrastructure built into lazr.restful to automatically generate the WADL, but it was so cumbersome that I was ecstatic to remove it all for restish (at the time).
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation. I definitely don't want to add a lot of cruft to the implementation - the light weight of the current falcon-based implementation is a huge benefit. It would be okay (maybe ideal) if some how the swagger spec was integrated with the core's test suite, so that at least we'd see failures if the API were modified (e.g. new resources and methods added) without the spec being similarly updated.
Ultimately I think if it isn't much effort to keep up to date, and is useful to consumers of the API, it could be a good thing, but I don't really have any opinions about swagger as compared to alternatives.
Cheers, -Barry
Barry Warsaw writes:
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation.
Doesn't Andrew's use case answer that? I mean, if the Swagger spec is out of date, the tests based on it should fail. If the tests don't fail, they're incomplete anyway, and that's a different problem that no spec language can solve for you.
As a matter of process, if Swagger is readable enough, we make it *the* spec, and you don't accept pull requests for the REST implementation without a patch to the spec. If Swagger isn't usable in that fashion, I suppose it will go away again like WADL as soon as Andrew loses interest in keeping it up to date. ;-)
" as soon as Andrew loses interest in keeping it up to date.”
;-) I was never interested in keeping it up to date in the first place but I can’t stand doing development without API documentation, a necessary first step to coding to the API.
I do like your idea about changes to the API not being complete until they have been implemented into the JSON spec.
On 12 Jan 2015, at 12:46 pm, Stephen J. Turnbull <stephen@xemacs.org> wrote:
Barry Warsaw writes:
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation.
Doesn't Andrew's use case answer that? I mean, if the Swagger spec is out of date, the tests based on it should fail. If the tests don't fail, they're incomplete anyway, and that's a different problem that no spec language can solve for you.
As a matter of process, if Swagger is readable enough, we make it *the* spec, and you don't accept pull requests for the REST implementation without a patch to the spec. If Swagger isn't usable in that fashion, I suppose it will go away again like WADL as soon as Andrew loses interest in keeping it up to date. ;-)
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
With Swagger you can either: 1: integrate the spec into the API source code or 2: have one single standalone JSON file that contains the whole specification (api-docs.json in this case)
I’m not a fan of integrating the Swagger specification into the code - seems to make for a VERY large amount of work, a huge amount of complexity and massive potential for introduction of bugs.
I’ve taken the approach of a single static JSON file - MUCH more simple. All Mailman would need is to include this file (api-docs.json) as a static file that can be read or if there is no static file server in Mailman (is there? I haven’t looked) maybe create an api-docs.json endpoint in the API that returns the static file. Any tools that want to use the api-docs.json spec file don’t need to be included in Mailman core.
The api-docs.json spec file would need to be kept up to date when the Mailman API changes but it’s really straightforward - building it in the first place is just tedious research on the methods and properties but maintaining it should be a matter of a few minutes work to update it when the API changes.
I’ll need to finish it up. I’m not sure what to do about getting a pair of eyes to QA verify it, but maybe we can cross that bridge after I’ve finished it.
On 12 Jan 2015, at 12:19 pm, Barry Warsaw <barry@list.org> wrote:
On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote:
It looks interesting. I have a little experience with WADL with the Launchpad API. There was a lot of infrastructure built into lazr.restful to automatically generate the WADL, but it was so cumbersome that I was ecstatic to remove it all for restish (at the time).
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation. I definitely don't want to add a lot of cruft to the implementation - the light weight of the current falcon-based implementation is a huge benefit. It would be okay (maybe ideal) if some how the swagger spec was integrated with the core's test suite, so that at least we'd see failures if the API were modified (e.g. new resources and methods added) without the spec being similarly updated.
Ultimately I think if it isn't much effort to keep up to date, and is useful to consumers of the API, it could be a good thing, but I don't really have any opinions about swagger as compared to alternatives.
Cheers, -Barry
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
On Jan 12, 2015, at 12:47 PM, Andrew Stuart wrote:
Agreed.
MM3 does not have a static file server, but I think we could serve the file as an API endpoint. Perhaps /<api>/api-docs.json or if that's difficult to implement, /<api>/system/api-docs.json.
I worry a little bit about the extra work to keep it up-to-date when I change the API, but maybe it won't be so bad in practice.
I wonder if there are any automated testing tools that can be integrated in the test suite. I.e. something that grabs the api-docs.json and then makes calls against the API to verify endpoints, arguments, and return values. Do you know of any such tool?
Sounds good!
Cheers, -Barry
Andrew Stuart writes:
Attached is a first pass at a Swagger spec for the REST API.
You can find out about Swagger at http://swagger.io
tmc;wr[1] Please explain briefly what Swagger is and why you're using it rather than some similar product. Two lines is enough. I have ZERO intention of paying attention to what you're doing; my technical plate is full, and Barry's the boss anyway. But if some new person or a GSoC student seems to have an interest in "that kind of thing" I'd like to know enough to say "go talk to Andrew".
Footnotes: [1] Too many clicks; won't read.
The Swagger spec defines a way to document the methods, properties and return values of a REST API using JSON, and also provides a front end user interface to turn that JSON into a functioning user interface to directly query the API. There seems to be a few choices for documentation REST APIs at the moment (http://apiary.io & http://www.mashery.com/product/io-docs) but Swagger appears to have the industry momentum.
I’ve put together a Swagger spec mainly because I’ve experienced enough pain with REST APIs in the past to know that development goes much, much more smoothly when you have a single place that shows all the available API methods, their parameters and return values, ideally live so you can see it working. Instead of digging through source code and written documentation to find how the REST API works, it’s all right there in front of you.
Once the REST API is documented in JSON, a range of things become possible including writing tests, command lines interfaces, clients and servers that “build themselves” to a greater or lesser extent directly from the JSON REST API spec.
Sorry, that was five long lines :-)
On 11 Jan 2015, at 4:23 pm, Stephen J. Turnbull <stephen@xemacs.org> wrote:
Andrew Stuart writes:
Attached is a first pass at a Swagger spec for the REST API.
You can find out about Swagger at http://swagger.io
tmc;wr[1] Please explain briefly what Swagger is and why you're using it rather than some similar product. Two lines is enough. I have ZERO intention of paying attention to what you're doing; my technical plate is full, and Barry's the boss anyway. But if some new person or a GSoC student seems to have an interest in "that kind of thing" I'd like to know enough to say "go talk to Andrew".
Footnotes: [1] Too many clicks; won't read.
On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote:
It looks interesting. I have a little experience with WADL with the Launchpad API. There was a lot of infrastructure built into lazr.restful to automatically generate the WADL, but it was so cumbersome that I was ecstatic to remove it all for restish (at the time).
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation. I definitely don't want to add a lot of cruft to the implementation - the light weight of the current falcon-based implementation is a huge benefit. It would be okay (maybe ideal) if some how the swagger spec was integrated with the core's test suite, so that at least we'd see failures if the API were modified (e.g. new resources and methods added) without the spec being similarly updated.
Ultimately I think if it isn't much effort to keep up to date, and is useful to consumers of the API, it could be a good thing, but I don't really have any opinions about swagger as compared to alternatives.
Cheers, -Barry
Barry Warsaw writes:
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation.
Doesn't Andrew's use case answer that? I mean, if the Swagger spec is out of date, the tests based on it should fail. If the tests don't fail, they're incomplete anyway, and that's a different problem that no spec language can solve for you.
As a matter of process, if Swagger is readable enough, we make it *the* spec, and you don't accept pull requests for the REST implementation without a patch to the spec. If Swagger isn't usable in that fashion, I suppose it will go away again like WADL as soon as Andrew loses interest in keeping it up to date. ;-)
" as soon as Andrew loses interest in keeping it up to date.”
;-) I was never interested in keeping it up to date in the first place but I can’t stand doing development without API documentation, a necessary first step to coding to the API.
I do like your idea about changes to the API not being complete until they have been implemented into the JSON spec.
On 12 Jan 2015, at 12:46 pm, Stephen J. Turnbull <stephen@xemacs.org> wrote:
Barry Warsaw writes:
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation.
Doesn't Andrew's use case answer that? I mean, if the Swagger spec is out of date, the tests based on it should fail. If the tests don't fail, they're incomplete anyway, and that's a different problem that no spec language can solve for you.
As a matter of process, if Swagger is readable enough, we make it *the* spec, and you don't accept pull requests for the REST implementation without a patch to the spec. If Swagger isn't usable in that fashion, I suppose it will go away again like WADL as soon as Andrew loses interest in keeping it up to date. ;-)
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
With Swagger you can either: 1: integrate the spec into the API source code or 2: have one single standalone JSON file that contains the whole specification (api-docs.json in this case)
I’m not a fan of integrating the Swagger specification into the code - seems to make for a VERY large amount of work, a huge amount of complexity and massive potential for introduction of bugs.
I’ve taken the approach of a single static JSON file - MUCH more simple. All Mailman would need is to include this file (api-docs.json) as a static file that can be read or if there is no static file server in Mailman (is there? I haven’t looked) maybe create an api-docs.json endpoint in the API that returns the static file. Any tools that want to use the api-docs.json spec file don’t need to be included in Mailman core.
The api-docs.json spec file would need to be kept up to date when the Mailman API changes but it’s really straightforward - building it in the first place is just tedious research on the methods and properties but maintaining it should be a matter of a few minutes work to update it when the API changes.
I’ll need to finish it up. I’m not sure what to do about getting a pair of eyes to QA verify it, but maybe we can cross that bridge after I’ve finished it.
On 12 Jan 2015, at 12:19 pm, Barry Warsaw <barry@list.org> wrote:
On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote:
It looks interesting. I have a little experience with WADL with the Launchpad API. There was a lot of infrastructure built into lazr.restful to automatically generate the WADL, but it was so cumbersome that I was ecstatic to remove it all for restish (at the time).
My big question is how to make sure that the swagger spec doesn't get out of date to the implementation. I definitely don't want to add a lot of cruft to the implementation - the light weight of the current falcon-based implementation is a huge benefit. It would be okay (maybe ideal) if some how the swagger spec was integrated with the core's test suite, so that at least we'd see failures if the API were modified (e.g. new resources and methods added) without the spec being similarly updated.
Ultimately I think if it isn't much effort to keep up to date, and is useful to consumers of the API, it could be a good thing, but I don't really have any opinions about swagger as compared to alternatives.
Cheers, -Barry
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
On Jan 12, 2015, at 12:47 PM, Andrew Stuart wrote:
Agreed.
MM3 does not have a static file server, but I think we could serve the file as an API endpoint. Perhaps /<api>/api-docs.json or if that's difficult to implement, /<api>/system/api-docs.json.
I worry a little bit about the extra work to keep it up-to-date when I change the API, but maybe it won't be so bad in practice.
I wonder if there are any automated testing tools that can be integrated in the test suite. I.e. something that grabs the api-docs.json and then makes calls against the API to verify endpoints, arguments, and return values. Do you know of any such tool?
Sounds good!
Cheers, -Barry
participants (3)
-
Andrew Stuart -
Barry Warsaw -
Stephen J. Turnbull