> 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 <[email protected]> wrote: > On Wed, Jan 28, 2015 at 11:29 PM, Brian Gerstle <[email protected]> > 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 <[email protected]> wrote: > > > > > On Wed, Jan 28, 2015 at 12:30 PM, James Douglas < > [email protected]> > > > 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/protocol.json > > > [1]: > > > > > > > > > https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome.js > > > _______________________________________________ > > > Wikitech-l mailing list > > > [email protected] > > > 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 > > [email protected] > > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > > > > Marko Obrovac > Senior Services Engineer > Wikimedia Foundation > _______________________________________________ > Wikitech-l mailing list > [email protected] > https://lists.wikimedia.org/mailman/listinfo/wikitech-l > _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
