search

PostgREST / postgrest

REST API for any Postgres database
https://postgrest.org
MIT License
23.43k stars 1.03k forks source link

Updating the self-documentation feature #449

Closed calebmer closed 8 years ago

calebmer commented 8 years ago

There are two places where I think PostgREST needs a little more polish, one is limiting embedded collections (which I'm trying to fix in #446), and the second is the self documentation feature.

I have been talking to some UX/design people recently and I really feel that with a little love, this feature could be really big for PostgREST as it allows a whole slew of awesome tooling, including custom CMS which use PostgREST as the backend (next gen of wordpress?). I don't know how many people use the feature now, but a mature and well developed self-documentation feature would be super awesome.

The current approach to self-documentation is an awesome proof of concept, but not as powerful as it could be. Some ideas for updating this system are moving to a new format like RAML, swagger, or json hyper-schema and having this information only be available at the root, /. No more OPTIONS requests, just a single large schema at /. I like this idea. However, if we are to go that way I would also recommend we move it to a new project, maybe postgrest-schema.

The new project wouldn't have to be written in Haskell, it could be written in any language. Go and Rust instantly come to mind, Node.JS might be a 3rd choice for it's JSON tools, however it does not compile down to a binary which could be a blocker (if someone wants to do it in Node, I'm not opposed).

Here is why I think it should be another project:

  1. Allows for easier maintainability. If a user wants to add their own routes to a schema they can just add a JSON or YML file to the file system and point the new project at it. Doing this in PostgREST core would be a design deviation.
  2. PostgREST couldn't support all the data formats (RAML, swagger, hyper-schema) without increased complexity and a whole bunch of specs to maintain support for. However, a separate project could.
  3. Faster iteration. As I do believe the schema could be huge for people developing a CMS, or other similar system, having a way to quickly iterate on schema representations could be helpful.
  4. Haskell isn't the best for manipulating complex data structures (I might be totally wrong on this one, this is just my experience in my short short time with Haskell).
  5. PostgREST shouldn't have exclusive access to /. The root route is important for API metadata, ideally PostgREST doesn't have exclusive access to it.

Even if we decide not to remove schema stuff from PostgREST core, I still believe a separate server for building a schema based on the PostgREST contract could be very powerful.

I currently don't have the time to invest in this schema project, however I feel like if anyone did there could be a large ROI, especially if they wanted to make a CMS with it. Is there anyone interested in developing this in their toolset of choice? This would be great if your a non-Haskell developer and want to contribute. Maybe adding a help-wanted tag to this issue could help people find it?

badri commented 8 years ago

Here's a proposal:

  1. Add to postgrest a --raml option which can contain an RAML file. This can be parsed and served at /.
  2. An option to generate an initial RAML spec from a postgres schema. This can be a separate cmdline tool. Take the file produced by pt. 2, edit/rinse/repeat and pass it as args to postgrest as mentioned in pt. 1. What do you guys think?
calebmer commented 8 years ago

@badri I really like this idea of the tool not being a server but rather just generating a file.

However, I also think that mounting the file at / should not be a feature of PostgREST but rather something done in NGINX or other proxy.

badri commented 8 years ago

@badri I really like this idea of the tool not being a server but rather just generating a file.

@calebmer ok, we could have an option in postgrest to generate RAML from DB.

However, I also think that mounting the file at / should not be a feature of PostgREST but rather something done in NGINX or other proxy.

I'm not clear how this will work in a production scenario. For ex, I'm thinking Postgrest will be deployed in Heroku or likewise using Procfile/foreman. How will serving the RAML spec work in that case? Forgive my ignorance in this matter :) Nevertheless, its a good idea to decouple this functionality from Postgrest, as it offers more scope for customization etc.

begriffs commented 8 years ago

Closing this as we now generate an OpenAPI spec.