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(a)wikimedia.org>
wrote:
On Wed, Jan 28, 2015 at 11:29 PM, Brian Gerstle
<bgerstle(a)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(a)wikimedia.org> wrote:
> On Wed, Jan 28, 2015 at 12:30 PM, James Douglas <
jdouglas(a)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/protoc…
https://github.com/cyrus-and/chrome-remote-interface/blob/master/lib/chrome…
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)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(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Marko Obrovac
Senior Services Engineer
Wikimedia Foundation
_______________________________________________
Wikitech-l mailing list
Wikitech-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l