API Explorer & docs

The API Explorer is your interactive testing ground for endpoints. Use it to verify endpoints work correctly before sharing them with consumers, and to troubleshoot issues.

Accessing the API Explorer

1. Go to API Explorer in the main menu
2. Select an API from the left sidebar

The explorer shows all endpoints for that API in the left panel. Select an endpoint to start testing.

Testing an endpoint

Anatomy of a request

The request panel has these sections:

• Method selector - dropdown to choose GET, POST, PUT, DELETE
• URL input - the full endpoint URL (auto-filled when you select an endpoint)
• Tabs - Headers, Params, Body, Auth (visible depending on method)

Making a request

1. Select an endpoint from the left sidebar
2. (Optional) Modify the Method if you want to use a different HTTP verb
3. (Optional) Add Headers (custom headers for the request):
   • Click the Headers tab
   • Add key-value pairs (e.g., Accept: application/json)
4. (Optional) Add Params:
   • Path parameters - values for {id} in the URL path (shown separately at top)
   • Query parameters - search and filter parameters (key-value pairs)
5. (Optional) Add Body (for POST/PUT methods):
   • Click the Body tab
   • Enter raw JSON data
6. (Optional) Configure Auth in the Auth tab:
   • Choose API Key and enter the key, or
   • Choose Bearer and enter a JWT token, or
   • Choose None for public endpoints
7. Click Send

The response appears in the lower panel with status code, response time, and body.

Understanding the response

After clicking Send, the response panel shows:

• Status code - HTTP status (e.g., 200 OK, 404 Not Found, 500 Error)
• Response time - latency in milliseconds
• Response body - raw response data (formatted as JSON)

Status codes:

• 2xx (green) - Success (e.g., 200 OK)
• 4xx (red) - Client error (e.g., 400 Bad Request, 404 Not Found, 401 Unauthorized)
• 5xx (red) - Server error (e.g., 500 Internal Server Error)

Troubleshooting requests

"404 Not Found"

• Verify the endpoint path is correct
• Confirm path parameters {id} are filled in correctly
• Check that the endpoint hasn't been deleted

"401 Unauthorized"

• Verify you've selected an Auth method in the Auth tab
• Confirm the API key or JWT token is valid
• Check that the key hasn't been revoked (go to Auth & Keys to verify)

"400 Bad Request" or validation error

• Check the Body tab for JSON syntax errors
• Verify required fields are included in the request
• For POST/PUT, ensure the data matches the table's column structure

Slow response or timeout

• Check the Response time - if very high, the query may be complex
• Reduce the Cache TTL setting on the endpoint to force fresh data
• Test the connection to the database (go to Connections > Test)

Response shows old data

• Verify the endpoint's Cache TTL is not too high
• Go to Endpoints, find the endpoint, and check the cache setting
• To bypass cache in testing, modify the URL with a unique query parameter (e.g., ?cache-bust=12345)

Editing endpoints in the explorer

While testing, you can edit an endpoint without leaving the explorer:

1. Click Edit (pencil icon) on the endpoint button
2. Modify fields:
   • Description - notes about the endpoint
   • Auth Type - change authentication method
   • Rate Limit - requests per minute
   • Cache TTL - response caching duration
3. Click Save Changes

Regenerating endpoints

If you've added tables to your database and want RestWard to create endpoints for them:

1. Select the API in the left sidebar
2. Click Regenerate in the endpoint list header (above the endpoint filter)

RestWard re-reads the database schema and rebuilds the auto-generated endpoints for that API. A status message appears when it finishes. This adds endpoints for new tables and updates existing ones; custom endpoints are preserved.

Using the built-in API documentation

RestWard generates documentation for your consumers. This documentation shows:

• All available endpoints
• Required parameters and authentication
• Example requests and responses
• Data model descriptions

Your organization has one published documentation portal, served by your API at its own hostname (the endpoint shown on the API's detail page):

https://YOUR-API-HOSTNAME/docs

If you've configured a Custom Domain, it's served from there instead (for example, https://docs.example.com/docs). Once published, open it directly from the View Documentation button on the Documentation page.

Customizing documentation

To customize how your documentation appears:

1. Go to Documentation in the main menu
2. Fill in:
   • Title - documentation page title
   • Description - overview text
   • Logo URL - your organization's logo (full URL)
   • Custom Domain - optional custom domain (e.g., docs.example.com). It must be a domain you verified on the Domains page, or a subdomain of one, and not used by another organization. The documentation is served on it only for your own API.
   • Primary Color - brand color (hex value, e.g., #2563EB)
   • Footer Text - copyright or credits
3. Click Save Branding
4. (Optional) Click Publish to make documentation public. Until then the portal (/docs) and the OpenAPI documents (/openapi.json, /openapi-enhanced.json) answer only requests with a valid X-API-Key for the API

Once published, your consumers can access the documentation at the published URL (or your custom domain if configured).

Timing. Your API reads the publish state again every 30 seconds, so Publish and Unpublish apply to the running API within 30 seconds: for up to 30 seconds after you unpublish, the documentation can still be read without a key.

Troubleshooting the explorer

"No APIs provisioned"

Create an API first. Go to APIs > New API and follow the setup wizard.

Endpoint list is empty

• Ensure the API has endpoints (endpoints are auto-generated when you create an API)
• Click Regenerate to create endpoints from your database schema
• If still empty, go to Endpoints and click Custom Endpoint to manually add one

"API keys unavailable" message in Auth tab

• Go to Auth & Keys and verify you have at least one API key created
• Create a new key if needed
• The explorer will refresh and show available keys

Can't access the published documentation

• Verify documentation is Published (status should show "published")
• If using a custom domain, ensure DNS and SSL/TLS are configured correctly
• Try accessing the default documentation URL first (without custom domain)

Documentation shows old endpoint definitions

• Regenerate endpoints in the explorer to update the schema
• Published documentation updates automatically
• Wait a few moments for caches to clear (up to 60 seconds)