PostgREST WriteAPI Save

Translate your OpenAPI specification into a NGinx config-file to implement your PostgREST system

Project README

We use the best, Nginx and PostgREST, to translate your OpenAPI specification into a plug-and-play back-end system.

The project offers automatic generation of the main piece for implementation of your endpoints, the Nginx configuration script — that acts as a primary dispatcher or controller, for PostgREST and for your system. In the context of a "microservices ecosystem", this controller do the microservices orchestration.


Terminological note: usually this piece of software is named reverse proxy or "API gateway".

Illustrating usage

After check pre-requisites (NodeJS v4.2), git clone this repo, you can generate an Nginx config-file with

cd PostgREST-writeAPI
node writeApi.js --tpl=01 --api=petstore-expanded | more

Edit api-spec/petstore-expanded.json and nginx-tpl/tpl01-baseBreak.mustache to try variations. What it do: transforms original localhost endpoints into specified endpoints.

Original endpoint Expected by API-specification
http://localhost:3000/pets or

So PostgREST-writeAPI generates the code below, a Nginx rewrite module script that implements the expected API‑gateway specification:

server {

	root /var/www/;

	# publishing by default the HTML for API description and related files for navigation
	index index.html index.htm;

	location / {
		try_files $uri $uri/ @proxy;

	location @proxy {
		### endpoints defined by OpenAPI spec of this app:

		rewrite    # endpoint "pets" for get,post

		rewrite    # endpoint "pets/{id}" for get,delete

		# endpoint insects (automatic PostgREST) for get
		rewrite    # endpoint "fishes TO OTHER PROXY" for get

		### default and auxiliar endpoint, for all other requests for PostgREST-queries
		rewrite     ^/api/(.*)$      /$1     break;
		### proxy configurations:
		proxy_pass  http://localhost:3000;  # my PostREST is  here!

It is obtained by tpl01-baseBreak template and this spec as input, as required by --tpl=01 --api=petstore-expanded options.

Variations can be obtained changing the template. Example: to stop to use the PostgREST queryes (eg. you can use --tpl=02 in the command line, that will generate script by tpl02-baseBreak-noQuery template, eliminating the last  rewrite clause.


PostgREST endpoints are ready-for-use, but, sometimes you can't reuse directally its "complex URL" endpoints, or need compliance with system requirements — already expressed in an formal specification.

This project was developed to simplify this PostgREST use case: to obey the OpenAPI specification of your project.

Need for fast prototipation

PostgreSQL is not an "agile tool"? We can go from scratch to a set of endpoints serving a database, in minutes? We can use only the database, alone, to implement web-application prototypes?

With PostgREST we can (!!) and the goal of this project is to expand the spectrum of applications. We can extend the PostgREST capabilties to "plug-and-play" endpoints, by its OpenAPI specifications.

OpenAPI addictions to specify your system

Your application can use full stack PostgREST (the URL-SQLquery syntax) for default endpoints, and two new fields must be included in your OpenAPI spec (your swagger.json), to describe the endpoints with non-default PostgREST behaviour:

  • x-rewrite_regex: the regular expression that in fact represents the endpoint is a concatenation of basePath, localPath and rewrite_regex.

  • x-rewrite_url: the target-URL with optional regex-variables (eg. $1).

  • x-proxy_url: the URL of the "root" that is handling the x-rewrite_url, when is not PostgREST (the default proxy). 

When one or both are declared at JSON's API description, it is translated to Nginx rewrite directive. Else default PostgREST is adopted. The x- prefix is the "vendor extension" of OpenAPI.


As the project is alpha version, have good methodology but not an automatic procedure. Simple steps:

  1. Prepare an OpenAPI specification of your system or application. Use basic PostgREST where is possible, where is not, two alternatives: rewrite to proxy-PostgREST or implement in it in other "proxy"... So, express also in the API specification the fields x-proxy_url, x-rewrite_regex and x-rewrite_url.

  2. Check what templete you need (or colabore creating a new one!). See nginx-tpl folder with some examples (or use template 01 as first try).

  3. Save your API specification (swagger.json) at api-spec with your project's name (eg. myproj.json), and edit it ading the fields xx and yy.

  4. run node writeApi.js > subdomain.conf with correct parameters. It will generate the Nginx's script for your server's  /etc/nginx/sites-available.

  5. do next steps as usual Nginx implementation

OpenAPI stadanrds and parallel initiatives

Please help to start, at Swagger-API community, via this swagger-codegen approved proposal, a new code generator, like here, but plugged into an ecosystem of standard code generators.

Open Source Agenda is not affiliated with "PostgREST WriteAPI" Project. README Source: ppKrauss/PostgREST-writeAPI
Open Issues
Last Commit
6 years ago

Open Source Agenda Badge

Open Source Agenda Rating