Quick Start

This guide takes you from a database to a working request against your generated REST API. You need a RestWard account with an organization (Getting started) and a PostgreSQL, MySQL, SQL Server, Oracle or IBM Db2 database that RestWard can reach over the network.

The examples use the Chinook sample database (artists, albums, tracks, invoices), so every response below is real output from a generated API.

1. Connect your database and generate the API

Pick one of the two routes. Both create a database connection and an API over it.

With the CLI (one command, also issues an API key):

dotnet tool install -g restward
restward login --base-url https://api.restward.tech
restward connect chinook --connection-string "postgresql://api_reader:s3cret@db.example.com:5432/chinook"

connect prints the API's endpoint and a new API key (shown once, store it now). See Connect a database for connection-string formats. Skip to step 3.

In the dashboard:

1. Connections → Add Connection: enter the host, port, database and credentials, then test the connection (Connecting a database).
2. APIs → New API: name it, pick the connection, and list the schemas to expose under Included Schemas (for Chinook on PostgreSQL: public) (Building & publishing APIs).

Which tables become endpoints

Every table (not views) in the included schemas that the connection's database user can see becomes an endpoint — minus the tables you exclude. Under Included Schemas on the New API form there is a table picker: it lists the real tables of the schemas you entered, and checking a table keeps it out of the API entirely (no endpoints, no routes, and it is left out of the OpenAPI document). You can change the excluded tables at any time with Edit API on the API's page. After Endpoints → Re-generate, you can also disable individual endpoints (for example the writes, to make a table read-only) and set each one's authentication, rate limit and cache (Building & publishing APIs).

2. Create an API key

In the dashboard, open Auth & Keys → New API Key, select your API and a role, and copy the key: it is shown only once (API keys & tenant API auth).

3. Make your first request

Your API's base URL is its endpoint, shown on the API's detail page in the dashboard and by restward list. Every API has a hostname of its own, for example https://chinook-test-org-vzubqp.run.restward.tech: your API slug, your organization slug and a short suffix derived from your organization, under run.restward.tech. The examples in these docs write it as https://YOUR-API-HOSTNAME; replace it with your API's endpoint. Every table is served at /api/<schema>/<table>. Put the endpoint and key in environment variables:

export RESTWARD_API_URL="https://YOUR-API-HOSTNAME"   # replace with your API's endpoint
export RESTWARD_API_KEY="rw_..."                       # the key from step 2

Then read three artists:

curl -s "$RESTWARD_API_URL/api/public/artist?limit=3" \
  -H "X-API-Key: $RESTWARD_API_KEY"

const res = await fetch(`${process.env.RESTWARD_API_URL}/api/public/artist?limit=3`, {
  headers: { "X-API-Key": process.env.RESTWARD_API_KEY },
});
console.log(await res.json());

import os, requests

res = requests.get(
    f"{os.environ['RESTWARD_API_URL']}/api/public/artist",
    params={"limit": 3},
    headers={"X-API-Key": os.environ["RESTWARD_API_KEY"]},
)
print(res.json())

using var http = new HttpClient { BaseAddress = new Uri(Environment.GetEnvironmentVariable("RESTWARD_API_URL")!) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("RESTWARD_API_KEY"));

Console.WriteLine(await http.GetStringAsync("/api/public/artist?limit=3"));

[
  { "artist_id": 1, "name": "AC/DC" },
  { "artist_id": 2, "name": "Accept" },
  { "artist_id": 3, "name": "Aerosmith" }
]

A list is a plain JSON array of rows; column names are exactly those of your table. One row by primary key:

curl -s "$RESTWARD_API_URL/api/public/album/1" -H "X-API-Key: $RESTWARD_API_KEY"

{ "album_id": 1, "title": "For Those About To Rock We Salute You", "artist_id": 1 }

4. Read the OpenAPI document

Every API describes itself. Fetch the spec with the same key:

curl -s "$RESTWARD_API_URL/openapi.json" -H "X-API-Key: $RESTWARD_API_KEY"

{
  "openapi": "3.0.3",
  "info": { "title": "Chinook", "version": "1.0.0" },
  "paths": {
    "/api/public/album": { "get": { "summary": "List album records", "...": "..." }, "post": { "...": "..." } },
    "/api/public/album/{id}": { "get": { "...": "..." }, "put": { "...": "..." }, "delete": { "...": "..." } }
  }
}

/openapi-enhanced.json is the same API with stable operationIds and your documentation branding, which is the better input for generating a client.

Connect Db2

IBM Db2 for Linux, UNIX and Windows (LUW) works the same way, with three differences: you always name the database (Db2 cannot list a server's databases), the API covers the connecting user's schema, and table and column names are Db2's upper-case identifiers.

restward connect chinook-db2 --connection-string "db2://db2inst1:s3cret@db2.example.com:50000/CHINOOK?sslmode=disable"

In the dashboard, pick IBM Db2, enter the database name (for example CHINOOK or SAMPLE; default port 50000) and include the schema of the connecting user, in upper case (DB2INST1). For a TLS port (often 50001), keep Use SSL on and paste the server's certificate into Server certificate if it is not signed by a CA RestWard already trusts; with the CLI, pass --server-certificate <file> (Connect a database). Over TLS, verified connections are reused only by requests with exactly the same settings, so a TLS Db2 API is as fast as a plain one; changing or removing the certificate takes effect within about 30 seconds. Db2 passwords cannot contain ; or start or end with a space (limitations of IBM's driver).

The endpoints are /api/<SCHEMA>/<TABLE>, and the query parameters use the column names as they are in Db2:

curl -s "$RESTWARD_API_URL/api/DB2INST1/ARTIST/1" -H "X-API-Key: $RESTWARD_API_KEY"

{ "ARTIST_ID": 1, "NAME": "AC/DC" }

curl -s "$RESTWARD_API_URL/api/DB2INST1/ALBUM?ARTIST_ID=2&sort=-TITLE&fields=ALBUM_ID,TITLE" \
  -H "X-API-Key: $RESTWARD_API_KEY"

[
  { "ALBUM_ID": 3, "TITLE": "Restless and Wild" },
  { "ALBUM_ID": 2, "TITLE": "Balls to the Wall" }
]

Filters, sorting, fields, count, writes and error codes behave as on the other databases (see Next steps). One difference: a duplicate-key 409 from Db2 does not name the constraint. Tables are exposed, views are not. Db2 for z/OS and Db2 for i (AS/400) are not supported.

Connect Oracle

Oracle works the same way, with two differences: you connect by the database's service name (the EZConnect form), not by SID or connect descriptor, and table and column names are Oracle's upper-case identifiers.

restward connect chinook-oracle --connection-string "oracle://chinook:s3cret@oracle.example.com:1521/FREEPDB1?sslmode=require"

In the dashboard, pick Oracle, enter the service name (default port 1521) and keep Use SSL on — Oracle keeps TLS on by default (tcps:// or no prefix keeps TLS on, only tcp:// turns it off), and the API covers the connecting user's schema, in upper case (CHINOOK). Unlike Db2, there is no Server certificate setting (no --server-certificate option): the server certificate must chain to a CA RestWard already trusts. If the listener requires a client certificate (mutual TLS), with the CLI pass --client-wallet ./wallet/cwallet.sso (Connect a database).

The endpoints are /api/<SCHEMA>/<TABLE>, and the query parameters use the column names as they are in Oracle:

curl -s "$RESTWARD_API_URL/api/CHINOOK/ARTIST/1" -H "X-API-Key: $RESTWARD_API_KEY"

{ "ARTIST_ID": 1, "NAME": "AC/DC" }

curl -s "$RESTWARD_API_URL/api/CHINOOK/ALBUM?ARTIST_ID=2&sort=-TITLE&fields=ALBUM_ID,TITLE" \
  -H "X-API-Key: $RESTWARD_API_KEY"

[
  { "ALBUM_ID": 3, "TITLE": "Restless and Wild" },
  { "ALBUM_ID": 2, "TITLE": "Balls to the Wall" }
]

Filters, sorting, fields, count, writes and error codes behave as on the other databases (see Next steps).

Next steps

• Authentication: API keys, JWT bearer tokens and mTLS
• List & read and Filtering
• Create, update & delete
• Errors & rate limits