Skip to content

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

License

Notifications You must be signed in to change notification settings

ppKrauss/PostgREST-writeAPI

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

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

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published