Understanding DBGate API and Edit Page Endpoints

Table of Contents

Introduction
API Endpoints
Edit Page Endpoints
Home Page Endpoints
Login Page Endpoints
Authentication Endpoints
Application Management Endpoints
Static Files

Introduction

DBGate provides several categories of endpoints:

Static files
Application management endpoints
Connection-based endpoints

Connection-based endpoints include:

API endpoints
Edit page endpoints
Home page endpoints
Login page endpoints
Authentication endpoints

DBGate generates connection-based endpoints for each connection defined in the appsettings file.

For example, appsettings.json might look like this:

{
  "ConnectionStrings": {
    "mssql": {
      "ProviderName": "System.Data.SqlClient",
      "ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=master;User ID=user;Pwd=pass"
    }
  }
}

DBGate will then serve the following base endpoints:

https://dbgate/api/mssql/
https://dbgate/edit/mssql/
https://dbgate/home/mssql/
https://dbgate/login/mssql
https://dbgate/auth/mssql/

In this example, api, edit, home, login, and auth are root segments.

You can change root segment names in the appsettings file.

Root and Connection Segments

By default, DBGate supports two orders for the root and connection segments:

https://dbgate/api/mssql/
https://dbgate/mssql/api/

You can set the desired order using the ConnectionSegment setting in the appsettings file.

Language Segments

DBGate allows you to specify the desired culture in the URL, such as:

https://dbgate/edit/mssql/en-us/
https://dbgate/edit/mssql/en-gb/

The JavaScript client uses the culture to load language resources and format dates and numbers.

It passes the culture to the DBGate backend as follows:

https://dbgate/api/mssql/en-us/
https://dbgate/api/mssql/en-gb/

DBGate uses the culture to translate model elements (names, comments, etc.) if configured in the database.

Additionally, DBGate passes the culture to stored procedure parameters defined in the LanguageParameters setting, enabling the return of translated data from stored procedures.

For more details, see the Developer Guide.

Language Folders

You can place language-specific files in wwwroot subfolders named after the culture, such as en-us, zh-hans, etc.

When a user specifies a culture in the URL (e.g., /en-us/, /en-gb/, or /zh-cn/), DBGate looks for the most appropriate folder.

For example, /edit/mssql/en-gb/ will load edit.htm from the wwwroot folder, while /edit/mssql/zh-cn/ will load wwwroot/zh-hans/edit.htm.

For static files, requests like /en-gb/sample01.htm and /zh-cn/sample01.htm will load from wwwroot/en-us/sample01.htm.

You can customize the default language folder using the DefaultLanguageFolder setting.

Container Segments

By default, DBGate includes all database objects available to the user in the web service model.

DBGate creates a default container.

You can add a specific container after the connection segment. The following URLs yield the same model:

https://dbgate/api/mssql/
https://dbgate/api/mssql/default/
https://dbgate/api/mssql/default/en-us/

Developers can create special views (of the QueryList type) to select specific database objects, such as buyer and seller. In this case, DBGate allows using these views as container names:

https://dbgate/api/mssql/buyer/
https://dbgate/api/mssql/seller/

In both cases, the model includes all objects available to the user, but the service documents reflect objects defined in the QueryList views.

For further details, see the Developer Guide.

API Endpoints

API endpoints return service documents, metadata, and data according to OData standards and extended settings.

DBGate creates a set of endpoints for each connection specified in the appsettings file.

Endpoint formats (with the first API root segment):

<domain>/<API root>/<connection name>/
<domain>/<API root>/<connection name>/<container name>/
<domain>/<API root>/<connection name>/<container name>/<language>/
<domain>/<API root>/<connection name>/<language>/

As mentioned, you can swap the API root and connection name segments.

The default root is api, which you can customize in the ApiRoot setting in the appsettings file.

Endpoint examples:

The basic endpoints return service documents. To return metadata, append $metadata to the URL. To retrieve data for a specific object, add its name.

For example:

DBGate supports the following extensions (in the last segment): $excel_formats, $excel_format, $table_format, $workbooks, $definition.

The $definition extension returns the object definition (if the user has the VIEW DEFINITION permission).

For example: https://dbgate.savetodb.com/api/mssql-023/usp_cashbook/$definition.

Other extensions may require additional database configuration.

Refer to the DBGate online examples and the Developer Guide for usage samples.

Edit Page Endpoints

Edit page endpoints return pages for viewing or editing database data.

DBGate creates endpoints for each edit root specified in the EditRoots setting in the appsettings file, following this template:

<domain>/<edit root>/<connection name>/
<domain>/<edit root>/<connection name>/<container name>/
<domain>/<edit root>/<connection name>/<container name>/<language>/
<domain>/<edit root>/<connection name>/<language>/

As noted, you can swap the edit root and connection name segments.

For example:

The first URL displays all available objects (from the service document), while the others show data for the specified objects.

The default root is edit, and the default page is edit.htm. You can configure multiple roots with different pages.

Note that edit pages use the window.location.href value to calculate the actual API URL.

For the example above, the edit pages request the following URLs:

Home Page Endpoints

Home page endpoints redirect to the service document edit pages or to pages configured in the Home settings.

The JavaScript client uses these endpoints in the Home button action.

DBGate creates endpoints for each connection specified in the appsettings file, following this template:

<domain>/<home root>/<connection name>/
<domain>/<home root>/<connection name>/<container name>/
<domain>/<home root>/<connection name>/<container name>/<language>/
<domain>/<home root>/<connection name>/<language>/

As mentioned, you can swap the home root and connection name segments.

You can customize the home root name in the HomeRoot setting in the appsettings file.

DBGate creates endpoints for each login root specified in the LoginRoots setting in the appsettings file, following this template:

<domain>/<login root>/<connection name>/
<domain>/<login root>/<connection name>/<container name>/
<domain>/<login root>/<connection name>/<container name>/<language>/
<domain>/<login root>/<connection name>/<language>/

As noted, you can swap the login root and connection name segments.

These pages do not require initial authentication credentials, allowing users to log in.

The default root is login, and the default page is login.htm. You can configure multiple roots with different pages, for example, to support sign-up.

Authentication Endpoints

Authentication endpoints support JWT authentication.

DBGate creates POST endpoints for each connection specified in the appsettings file, following this template:

<domain>/<auth root>/<connection name>/login
<domain>/<auth root>/<connection name>/logout
<domain>/<auth root>/<connection name>/refresh
<domain>/<auth root>/<connection name>/getToken

As noted, you can swap the auth root and connection name segments.

The default auth root is auth, which you can customize in the AuthRoot setting in the appsettings file.

The login endpoint returns access and refresh tokens, along with cookie and access token expiration times.

The access token and cookie are required to access protected resources, while the refresh token and cookie are needed to renew the access token.

You can customize the token expiration times using the AccessTokenExpirationInMinutes and RefreshTokenExpirationInMinutes settings.

The logout endpoint clears access and refresh tokens on the server side.

The refresh endpoint returns a new access token and its expiration time, and may also return a new refresh token and cookie.

The getToken endpoint provides a one-time access token, allowing access to protected resources that do not support JavaScript.

DBGate implements JWT authentication following best practices.

You can check the implementation details using your browser's developer tools.

Note that you may not see the cookie in some queries, as they are set for the API and auth roots only with SameSite=Strict; HttpOnly=true.

Application Management Endpoints

You can use the following POST endpoints to manage the console application, such as stopping it or showing/hiding its window on the Windows platform:

<domain>/<app root>/stop
<domain>/<app root>/show
<domain>/<app root>/hide

For example:

https://localhost:5003/app/stop
https://localhost:5003/app/show
https://localhost:5003/app/hide

These operations are useful for integrating DBGate into your desktop applications.

These operations are available only for the Windows console application when StopEnabled is set to true.

The default app root is app, which you can customize in the AppRoot setting in the appsettings file.

Static Files

DBGate serves static files from the wwwroot folder.

For example, it serves files like /css/db.min.css or /js/db.min.js, sending gzip content when applicable.

As mentioned earlier, DBGate processes language folders in a specific manner.

For instance, it will return the wwwroot/en-us/sample01.htm file for the /en-gb/sample01.htm request if the wwwroot/en-gb/sample01.htm file does not exist.

DBGate supports the following index pages: default.htm, default.html, index.htm, index.html.

DBGate automatically adjusts the <base href="/" /> tag in HTML files for IIS applications.

Understanding DBGate API and Edit Page Endpoints

Introduction

Root and Connection Segments

Language Segments

Language Folders

Container Segments

API Endpoints

Edit Page Endpoints

Home Page Endpoints

Login Page Endpoints

Authentication Endpoints

Application Management Endpoints

Static Files