by • November 28, 2023
Storing information in a relational database and sharing it via a RESTful API is a very common scenario these days. Depending on your RDBMS (relational database management system), this may take a lot of development effort. One solution that attempts to simplify the process is the PostgREST web server add-on for PostgreSQL.
If your organization uses the PostgreSQL database, PostgREST quickly adds basic CRUD (create, read, update, delete) functions in an easy-to-use RESTful HTTP interface. But while PostgREST does the API generation well, it may lack other features for more complex projects.
While PostgREST is a handy utility, it is somewhat limited in scope. A more full-featured API management solution may be needed for many enterprise users. Here’s a look at how PostgREST works, its pros and cons, and what you can do with it.
Table of Contents
Generate a full-featured, documented, and secure REST API in minutes.
PostgreSQL is an open-source, enterprise-class RDBMS that supports both SQL for relational querying and non-relational querying via JSON. Also known informally as Postgres, PostgreSQL has been a popular choice for enterprises for decades, thanks to performance that’s in the same class as commercial database systems like Oracle and Microsoft SQL Server.
Postgres features the PL/pgSQL procedural language for complex and programmatic query operations. With PL/pgSQL, database administrators have access to a C-style language that supports functions, procedures, and triggers.
PL/pgSQL and the support for JSON have made PostgreSQL a popular choice for developers who need more complex data management than standard SQL offers. This has made Postgres a popular choice as the data store for web services, mobile apps, data warehousing, and analytics operations.
PostgREST is a free web server add-on for PostgreSQL that is available for download from the project’s GitHub page. It’s written in the Haskell language with the Warp HTTP framework. Available for Linux and Windows, PostgREST serves up a fully RESTful API from any Postgres database.
Once you have downloaded PostgREST, most of the setup is complete. PostgREST is simply used to make an API call to the Postgres HTTP interface. With that in mind, here’s a quick tutorial on how you might set up a PostgreSQL schema with data to be served up by the API.
PostgREST is significant because it provides an efficient, scalable, and secure way to convert any PostgreSQL database into a RESTful API. This approach streamlines the development process by allowing direct access to a database through a web API, which can be particularly useful for web and mobile applications. It eliminates the need for manual coding of backend logic, as the database schema itself defines the API endpoints, leading to rapid development and easier maintenance.
PostgREST enforces robust security measures and embraces PostgreSQL’s powerful features, including its role-based access control and advanced query capabilities. This makes it a valuable tool for developers looking to create high-performance, secure, and scalable web services with minimal overhead.
To show you how to get started with PostgREST, you’ll want to create an API schema using the psql tool:
CREATE SCHEMA api;
Then create a table within that schema with data for the API to serve up. In this example, you’ll create a simple table for a list of books with these columns and data types:
CREATE TABLE api.books (
Note that the index column has the SERIAL type, which means it will create an auto-incremented ID for every row created in the table. To get started, enter a few rows, each with a book title, author, and genre.
PostgREST delegates security to the database, using PostgreSQL roles as the RESTful API users. You’ll want to create a role with minimal privileges. In this example, the role is called apiOperator. It will not be able to log in to the server and will only have permissions to the books table via API:
CREATE ROLE apiOperator nologin;
GRANT usage ON SCHEMA api TO apiOperator;
GRANT all ON api.books TO apiOperator;
GRANT usage, SELECT ON SEQUENCE api.books_index_seq TO operator;
This completes a basic configuration on the Postgres side, and you’re now ready to move on to configuring PostgREST to talk to your database server.
PostgREST uses postgrest.conf, a simple configuration file that contains just a few variables. You’ll need to provide the URI for your Postgres server, along with the schema containing your data to be retrieved by API calls and the role with which you’ll make a connection.
For this example, we’ll assume you’re running PostgREST on the same server as your PostgreSQL database (localhost). As outlined above, our example schema is api, and the name of the role is apiOperator. Place these parameters in the config file like this:
db-uri = "localhost"
db-schema = "api"
db-anon-role = "apiOperator"
Once you have the configuration file saved, you’re ready to make your first API call with the help of PostgREST.
Assuming that you’re running PostgREST on localhost along with your database server as outlined above, the following HTTP request will return all rows from your books table:
PostgREST supports a wide range of filters to limit the results returned. For example, to get the first five rows from the books table, use this curl request:
You can also select which columns from the table you would like returned. This request will return only the book title and author from the first five rows:
As previously mentioned, PostgREST can perform full CRUD functions. The above examples show the R (“read”) part in action. Here’s a way to create a new record:
curl "http://localhost:3000/books" \
-X POST -H "Content-Type: application/json" \
"author": "Ernest Hemingway",
"title": "The Sun Also Rises"
And here is how you can delete that record that was just added:
curl -X DELETE "http://localhost:3000/books?title=like.”The Sun*"
Out of the box, PostgREST offers the following features:
While PostgresREST does API generation well, it lacks features for more complex projects. Many users still need to have the ability to customize the API, send emails, and add any additional custom business logic.
Achieving these goals will require combining PostgreSQL’s features, custom programming, and using some of the open-source apps and extensions for PostgREST.
In the end, PostgREST is simply a web server that can turn your PostgreSQL database into a REST API. This removes the need to create your CRUD endpoints manually, but it doesn’t offer much more without considerable extra work. With that in mind, here’s a rundown of the pros and cons of PostgREST.
With all this in mind, PostgREST will have limited utility in the enterprise. Unless your entire digital strategy is built around a Postgres data warehouse—and you have the developer resources to extend the limited functionality of PostgREST—you will need a more comprehensive API management solution.
As most organizations have multiple applications and services they support, an API management platform is likely to be better suited to your overall needs.
An API management platform covers the entire API development lifecycle for all of your systems, including PostgreSQL. An API management platform offers other benefits, including:
API management platforms allow you to centralize all of your API needs—for all of your systems. Rather than being focused on one particular backend service, like PostgREST with PostgreSQL, a good management tool will guide you through the process of API creation, deployment, versioning, and more.
Most organizations will find that API management’s more comprehensive solutions make them more attractive than one-off solutions. The only thing left to do is find the right platform for your organization.
If you do not believe PostgREST meets your needs, consider learning more about DreamFactory’s PostgreSQL connector. DreamFactory has an intuitive dashboard that gives everyone the access control they require to manage their APIs. Many users love DreamFactory because it can automatically generate REST APIs from PostgreSQL. Other benefits include:
DreamFactory provides a complete API management solution for all of your systems, in one central location. Discover the advantage of managing and creating APIs with DreamFactory by signing up for a free 14-day trial.
Kevin McGahey is an accomplished solutions engineer and product lead with expertise in API generation, microservices, and legacy system modernization, as demonstrated by his successful track record of facilitating the modernization of legacy databases for numerous public sector organizations.
Join the DreamFactory newsletter list.