Howdy all,
It was a pleasure chatting with you at this year's Developer Summit[1] about how we might give SOA a shot in the arm by creating (and building from) specifications.
The slides are available on the RESTBase project pages[2] and the session notes are available on Etherpad[3].
I'm eager to keep the conversation going on the mailing list, and want to address a couple items that came up (or were missing) during the session, as well as prompt for further discussion.
I mentioned after the presentation that we're using our spec to drive our automated testing. I added some info about that to slide #14 in the slides[2]. The idea is that, since Swagger lets us add custom fields to a spec, we can augment each endpoint specification with a functional description of its expected inputs and outputs. During testing, we parse the spec and verify that these indeed hold true. There's a lot of opportunity for enhancement of our (currently very basic) approach to this, but it's already proving pretty handy from a coverage standpoint.
There was a question in the notes[3] about Swagger's support for internationalization, but I'm not familiar with the use case in mind. How might an API differ, aside from the content of fields in a specified model, under different localizations? Might users want the models themselves (or parameter names, etc.) to vary?
Cheers! James
[1] https://www.mediawiki.org/wiki/MediaWiki_Developer_Summit_2015 [2] http://wikimedia.github.io/restbase/docs/presentations/wm-dev-summit-2015/so... [3] https://etherpad.wikimedia.org/p/mwds15-spec-oriented-architecture
On Wed, Jan 28, 2015 at 12:30 PM, James Douglas jdouglas@wikimedia.org wrote:
Howdy all,
It was a pleasure chatting with you at this year's Developer Summit[1] about how we might give SOA a shot in the arm by creating (and building from) specifications.
The slides are available on the RESTBase project pages[2] and the session notes are available on Etherpad[3].
Hi James,
I missed your session at the developer summit, so the slides and notes are very useful. I think that having a formal specification for an API as a standalone, machine-readable document is a great idea. I have been poking at Chrome's Remote Debugging API this week and found this project, which is a cool demonstration of the power of this approach: https://github.com/cyrus-and/chrome-remote-interface
The library consists of just two files: the protocol specification[0], which is represented as a JSON Schema, and the library code[1], which generates an API by walking the tree of objects and methods. This approach allows the code to be very concise. If future versions of the remote debugging protocol are published as JSON Schema files, the library could be updated without changing a single line of code.
MediaWiki's API provides internal interfaces for API modules to describe their inputs and outputs, but that's not quite as powerful as having the specification truly decoupled from the code and published as a separate document. I'm glad to see that you are taking this approach with RestBASE.
[0]: https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/protoco... [1]: https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome....
JSON Schema is a recurring theme here which I'd like to encourage. I've thought it was a promising idea and would like to explore it further, both on the client and server side. If we can somehow keep data schema and API specifications separate, it would be nice to develop both of these ideas in parallel.
On Wed, Jan 28, 2015 at 10:57 PM, Ori Livneh ori@wikimedia.org wrote:
On Wed, Jan 28, 2015 at 12:30 PM, James Douglas jdouglas@wikimedia.org wrote:
Howdy all,
It was a pleasure chatting with you at this year's Developer Summit[1] about how we might give SOA a shot in the arm by creating (and building from) specifications.
The slides are available on the RESTBase project pages[2] and the session notes are available on Etherpad[3].
Hi James,
I missed your session at the developer summit, so the slides and notes are very useful. I think that having a formal specification for an API as a standalone, machine-readable document is a great idea. I have been poking at Chrome's Remote Debugging API this week and found this project, which is a cool demonstration of the power of this approach: https://github.com/cyrus-and/chrome-remote-interface
The library consists of just two files: the protocol specification[0], which is represented as a JSON Schema, and the library code[1], which generates an API by walking the tree of objects and methods. This approach allows the code to be very concise. If future versions of the remote debugging protocol are published as JSON Schema files, the library could be updated without changing a single line of code.
MediaWiki's API provides internal interfaces for API modules to describe their inputs and outputs, but that's not quite as powerful as having the specification truly decoupled from the code and published as a separate document. I'm glad to see that you are taking this approach with RestBASE.
[0]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/protoco... [1]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome.... _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Wed, Jan 28, 2015 at 11:29 PM, Brian Gerstle bgerstle@wikimedia.org wrote:
JSON Schema is a recurring theme here which I'd like to encourage. I've thought it was a promising idea and would like to explore it further, both on the client and server side. If we can somehow keep data schema and API specifications separate, it would be nice to develop both of these ideas in parallel.
That's exactly our idea for RESTBase/SOA. Each interface would be packaged separately as a swagger specification, which would then be required by and implemented by modules. Having such a clean and clear separation of the two would allow us to: - consult the interface independently of the implementation - have multiple modules implementing the same interface
As to JSON, IMHO YAML is better, more human-readable and less verbose, but that's just a matter of personal preference - computers can read them all :P
Marko
On Wed, Jan 28, 2015 at 10:57 PM, Ori Livneh ori@wikimedia.org wrote:
On Wed, Jan 28, 2015 at 12:30 PM, James Douglas jdouglas@wikimedia.org wrote:
Howdy all,
It was a pleasure chatting with you at this year's Developer Summit[1] about how we might give SOA a shot in the arm by creating (and building from) specifications.
The slides are available on the RESTBase project pages[2] and the
session
notes are available on Etherpad[3].
Hi James,
I missed your session at the developer summit, so the slides and notes
are
very useful. I think that having a formal specification for an API as a standalone, machine-readable document is a great idea. I have been poking at Chrome's Remote Debugging API this week and found this project, which
is
a cool demonstration of the power of this approach: https://github.com/cyrus-and/chrome-remote-interface
The library consists of just two files: the protocol specification[0], which is represented as a JSON Schema, and the library code[1], which generates an API by walking the tree of objects and methods. This
approach
allows the code to be very concise. If future versions of the remote debugging protocol are published as JSON Schema files, the library could
be
updated without changing a single line of code.
MediaWiki's API provides internal interfaces for API modules to describe their inputs and outputs, but that's not quite as powerful as having the specification truly decoupled from the code and published as a separate document. I'm glad to see that you are taking this approach with
RestBASE.
[0]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/protoco...
[1]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome....
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
-- EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle IRC: bgerstle _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Marko Obrovac Senior Services Engineer Wikimedia Foundation
As to JSON, IMHO YAML is better, more human-readable and less verbose
I agree. As a human, YAML is rather nicer to read (and write) than JSON. Fortunately it's pretty easy to convert one to the other. We've even made some tweaks to Swagger UI to support both YAML and JSON, and we're currently generating our tests from a YAML-formatted version of our Swagger spec.
On Thu, Jan 29, 2015 at 12:31 AM, Marko Obrovac mobrovac@wikimedia.org wrote:
On Wed, Jan 28, 2015 at 11:29 PM, Brian Gerstle bgerstle@wikimedia.org wrote:
JSON Schema is a recurring theme here which I'd like to encourage. I've thought it was a promising idea and would like to explore it further,
both
on the client and server side. If we can somehow keep data schema and
API
specifications separate, it would be nice to develop both of these ideas
in
parallel.
That's exactly our idea for RESTBase/SOA. Each interface would be packaged separately as a swagger specification, which would then be required by and implemented by modules. Having such a clean and clear separation of the two would allow us to:
- consult the interface independently of the implementation
- have multiple modules implementing the same interface
As to JSON, IMHO YAML is better, more human-readable and less verbose, but that's just a matter of personal preference - computers can read them all :P
Marko
On Wed, Jan 28, 2015 at 10:57 PM, Ori Livneh ori@wikimedia.org wrote:
On Wed, Jan 28, 2015 at 12:30 PM, James Douglas <
jdouglas@wikimedia.org>
wrote:
Howdy all,
It was a pleasure chatting with you at this year's Developer
Summit[1]
about how we might give SOA a shot in the arm by creating (and
building
from) specifications.
The slides are available on the RESTBase project pages[2] and the
session
notes are available on Etherpad[3].
Hi James,
I missed your session at the developer summit, so the slides and notes
are
very useful. I think that having a formal specification for an API as a standalone, machine-readable document is a great idea. I have been
poking
at Chrome's Remote Debugging API this week and found this project,
which
is
a cool demonstration of the power of this approach: https://github.com/cyrus-and/chrome-remote-interface
The library consists of just two files: the protocol specification[0], which is represented as a JSON Schema, and the library code[1], which generates an API by walking the tree of objects and methods. This
approach
allows the code to be very concise. If future versions of the remote debugging protocol are published as JSON Schema files, the library
could
be
updated without changing a single line of code.
MediaWiki's API provides internal interfaces for API modules to
describe
their inputs and outputs, but that's not quite as powerful as having
the
specification truly decoupled from the code and published as a separate document. I'm glad to see that you are taking this approach with
RestBASE.
[0]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/protoco...
[1]:
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome....
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
-- EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle IRC: bgerstle _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Marko Obrovac Senior Services Engineer Wikimedia Foundation _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
wikitech-l@lists.wikimedia.org