README.md

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	petstore.swagger.io/api/pets or petstore.swagger.io/api/darlings
http://localhost:3000/pets?id=eq.id	petstore.swagger.io/api/pets/{id}

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

server {

	server_name petstore.swagger.io;
	root /var/www/petstore.swagger.io/html;

	# 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
		  ^/api/(pets?|darlings?)$
		  http://localhost:3000/pets
		  break;

		rewrite    # endpoint "pets/{id}" for get,delete
		  ^/api/pets/([0-9]+)
		  http://localhost:3000/pets?id=eq.$1
		  break;

		# endpoint insects (automatic PostgREST) for get
		
		rewrite    # endpoint "fishes TO OTHER PROXY" for get
		  ^/api/fishes
		  http://localhost:4000
		  break;

		### 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. petstore.swagger.io/api/otherTable) you can use --tpl=02 in the command line, that will generate script by tpl02-baseBreak-noQuery template, eliminating the last  rewrite clause.

Motivations

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.

Methodology

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.