Postgrest: Support RAML description of API

[StefanScott]

Hi -

(This isn't really a question about any problem or issue involving PostgREST - but rather an exploratory question about possible opportunities for using PostgREST along with tools for documentation APIs, and possibly even generating simple CRUD front-ends based on a database schema, leveraging PostgREST.)

Recently I saw a free open-source tool called swagger.io which is used to document REST APIs.

http://en.wikipedia.org/wiki/Swagger_(computer_science)

http://swagger.io/

http://editor.swagger.io/#/

https://github.com/swagger-api/swagger-ui

https://github.com/swagger-api/swagger-spec/

http://petstore.swagger.io/#!/pet/getPetById

http://en.wikipedia.org/wiki/Web_API

It seems that swagger.io could be useful in combination with PostgREST.

They also apparently have some sort of tool which generates client code in different languages:

https://github.com/swagger-api/swagger-codegen

I'd like to use swagger.io with PostgREST. Currently, I'm unsure how to get started, so I'm still reading the documentation. It seems that the REST API has to expose an endpoint like:

https://postgrest.herokuapp.com/swagger.json

which would then provide discovery and documentation of the REST endpoints of the above Postgres database.

I guess first it would be necessary to create the swagger.json document for a given Postgres database.

Ultimately I think it would be interesting if it would be possibly not only to provide discovery and documentation of a given database, but also to generate a simple admin CRUD interface for the database, in a particular client language.

It looks like someone has already used swagger to develop generator which produces a simple admin CRUD interface from a database definition:

http://www.toobop.net/gform-admin/

https://github.com/stemey/gform-admin

I think at this point in history, it should be possible to combine certain notions of metaprogramming with web development frameworks to create admin CRUD interface generators based solely on a database schema (ie, a basic but modern web client providing standard layouts such as forms and grids supporting CRUD operations - including simple master-detail layouts, and custom field editors - eg data pickers for date fields, and drop-down menus for foreign-key fields).

This sort of thing has been available (typically in the form of "wizards") in many native (Windows, Linux, Apple) database application development environments (eg, Microsoft Access :-)

Now, with the power of today's web development frameworks and metaprogrammable languages, this sort of thing should also start becoming available for web-based database development as well.

I would like to learn more about how to combine swagger.io and PostgREST to do this sort of thing - to generate a variety of simple admin CRUD front-ends based on a PostgREST database schema, targeting a variety of front-end technologies, such as:

AngularJS:

https://github.com/marmelab/ng-admin

http://ng-admin.marmelab.com/#/dashboard

Backbone:

http://backbonethis.com/

etc.

It would be great if this sort of generator were available for the newer React/Flux frameworks and architectures, but they've only been around for a few months, so currently CRUD admin generators only seem to be available for a few of the more mature MVC Javascript frameworks and architectures (AngularJS, Ember, Knockout, Backbone).

This would be really DRY: just define your database schema, and get a simple working CRUD interface.

[begriffs]

Sure, generating a swagger definition would be cool, or RAML as suggested in #8

[jmorris644]

@StefanScott Have you proceeded any further in this effort?

[astewart-twist]

+1

[begriffs]

Planning to add RAML support after the 0.3 release. There is a lot of code in flux right now. Come join us in the chat room to learn more about what's going on: https://gitter.im/begriffs/postgrest

[begriffs]

@StefanScott we did not end up adding RAML to 0.3, but it seems like a good candidate for 0.4.

[sscarduzio]

+1

[devguf]

+1

[jogrms]

+1

[luismartingil]

+1

[pavelkogan]

+1

[FGRibreau]

Swagger gave birth to OpenAPI, supported by Google, IBM, Microsoft, Paypal, Apiary.
May be the good time to reconsider OpenAPI (swagger) over RAML?

[begriffs]

With support for OpenAPI now on the master branch I think we can close this!