Copple
a788003648
## What kind of change does this PR introduce? Updates the docs with the new developer experience: https://deploy-preview-253--supabase.netlify.app/docs - Documents the new Auth using `gotrue-js` - Fixes #179 - Fixes OAuth links https://github.com/supabase/supabase/issues/241#issuecomment-705632335 - [x] Add docs on Policies ## Additional context Related PR on `supabase-js` https://github.com/supabase/supabase-js/pull/50 * Updates the docs for the new Auth DX. * docs: adds docs for subscribing to rows * Updates all the reads * Updates all the docs with the new format * docs: Replaces all { error, data} with data first, because I subjectively think it looks better * Adds some of the breaking changes to a blog post * Adds headings * removes the blog post since it is now in notion * Adds the Oauth changes * removes recharts because we no longer use it * Adds basic structure for GoTrue ref * Adds styles for the api reference docs * Adds more generated docs * Downloads the files to work locally * Adds a supabase generator * Moves some of the guides into the "tools" folder * Re-shuffles some of the pages around * Generated everythign related to the Supabase Client * Refactors and categorieses the pages * Changes the names to be more readable * Migrates almost all of the filters into the API reference * Moves most of the stored procedure filters * Adds realtime-js to the mix * More desciptive titles * Moves all the generated docs to the docs folder * Moves over some of the data manipulators * Extracts most of the client functionality to the API ref * Adds more detail to the guides * Removes the reference to the emulator * Adds the supabase 1.0 blog post * Adds a redirects for netlify * chore: Updates packages * Updates broken links * Adding docs for the server * Adds comments to gotrue and pgapi * Adds a twitter icon to our navbar * Updates the auth with the new user and session return values * Updates the sponsors * Styles for cards * Adds a default value to all of the Tabs
3.8 KiB
id, title, description
| id | title | description |
|---|---|---|
| about | PostgREST | PostgREST is a standalone web server that turns your PostgreSQL database directly into a RESTful API. |
PostgREST is a standalone web server that turns your PostgreSQL database directly into a RESTful API.
The structural constraints and permissions in the database determine the API endpoints and operations.
Documentation
Latest documentation is at postgrest.org. You can contribute to the docs in PostgREST/postgrest-docs.
Performance
TLDR; subsecond response times for up to 2000 requests/sec on Heroku free tier. If you're used to servers written in interpreted languages, prepare to be pleasantly surprised by PostgREST performance.
Three factors contribute to the speed. First the server is written in Haskell using the Warp HTTP server (aka a compiled language with lightweight threads). Next it delegates as much calculation as possible to the database including
- Serializing JSON responses directly in SQL
- Data validation
- Authorization
- Combined row counting and retrieval
- Data post in single command (
returning *)
Finally it uses the database efficiently with the Hasql library by
- Keeping a pool of db connections
- Using the PostgreSQL binary protocol
- Being stateless to allow horizontal scaling
Security
PostgREST handles authentication (via JSON Web Tokens) and delegates authorization to the role information defined in the database. This ensures there is a single declarative source of truth for security. When dealing with the database the server assumes the identity of the currently authenticated user, and for the duration of the connection cannot do anything the user themselves couldn't. Other forms of authentication can be built on top of the JWT primitive. See the docs for more information.
PostgreSQL 9.5 supports true row-level security. In previous versions it can be simulated with triggers and security-barrier views. Because the possible queries to the database are limited to certain templates using leakproof functions, the trigger workaround does not compromise row-level security.
Versioning
A robust long-lived API needs the freedom to exist in multiple versions. PostgREST does versioning through database schemas. This allows you to expose tables and views without making the app brittle. Underlying tables can be superseded and hidden behind public facing views.
Self-documentation
PostgREST uses the OpenAPI standard to generate up-to-date documentation for APIs. You can use a tool like Swagger-UI to render interactive documentation for demo requests against the live API server.
This project uses HTTP to communicate other metadata as well. For instance the number of rows returned by an endpoint is reported by - and limited with - range headers. More about that.
Data Integrity
Rather than relying on an Object Relational Mapper and custom imperative coding, this system requires you put declarative constraints directly into your database. Hence no application can corrupt your data (including your API server).
The PostgREST exposes HTTP interface with safeguards to prevent surprises, such as enforcing idempotent PUT requests.
See examples of PostgreSQL constraints and the API guide.