Explore ODataDB Endpoints for API and Data Editing

Table of Contents

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

Introduction

ODataDB 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

ODataDB creates connection-based endpoints for each connection defined in the appsettings file.

For example, the appsettings.json file might look like this:

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

ODataDB will serve the following base endpoints:

https://odatadb/v4/mssql/
https://odatadb/edit/mssql/
https://odatadb/home/mssql/
https://odatadb/login/mssql
https://odatadb/auth/mssql/

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

You can change root segment names in the appsettings file.

Root and Connection Segments

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

https://odatadb/v4/mssql/
https://odatadb/mssql/v4/

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

Language Segments

ODataDB allows you to specify the desired culture in the URL, like so:

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

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

The client passes the culture to the ODataDB backend with URLs like:

https://odatadb/v4/mssql/en-us/
https://odatadb/v4/mssql/en-gb/

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

Additionally, ODataDB passes the culture to stored procedure parameters defined in the LanguageParameters setting, allowing for translated data to be returned from stored procedures.

See more details in 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 the culture in the URL (e.g., /en-us/, /en-gb/, or /zh-cn/), ODataDB searches 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/sample02.htm and /zh-cn/sample02.htm will load from the same wwwroot/en-us/sample02.htm.

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

Container Segments

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

ODataDB creates a default entity container in the default schema.

You can add a desired container after the connection segment.

The following URLs yield the same model:

https://odatadb/v4/mssql/
https://odatadb/v4/mssql/default/
https://odatadb/v4/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, ODataDB allows using these views as container names:

https://odatadb/v4/mssql/buyer/
https://odatadb/v4/mssql/seller/

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

See more in the Developer Guide.

API Endpoints

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

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

Endpoint formats (with the first API root segment) are as follows:

<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 earlier, you can swap the API root and connection name segments.

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

Examples of endpoints include:

The basic endpoints return service documents.

To retrieve metadata, append the $metadata segment.

To get data for a specific object, add the object name. Use round brackets for functions.

For example:

ODataDB 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, you can access the definition with: https://odatadb.savetodb.com/v4/mssql-023/usp_cashbook/$definition.

Other extensions may require additional database configuration.

Check out the ODataDB online examples and the Developer Guide for more details.

Edit Page Endpoints

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

ODataDB 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 previously mentioned, you can swap the edit root and connection name segments.

For example:

The first URL shows all available objects (from the service document), while the others display 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 examples above, the edit pages will request the following URLs:

Home Page Endpoints

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

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

ODataDB creates endpoints for each connection specified in the appsettings file, structured as follows:

<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 noted earlier, 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.

ODataDB 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 mentioned earlier, 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.

ODataDB creates POST endpoints for each connection specified in the appsettings file, structured as follows:

<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 earlier, 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 the access and refresh tokens, along with cookie and access token expiration times.

The access token and cookie are necessary for accessing protected resources, while the refresh token and cookie are used 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 for accessing protected resources that do not support JavaScript.

ODataDB 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 control the console application, such as stopping it or showing/hiding its window on Windows:

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

For example:

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

These operations are useful for integrating ODataDB 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

ODataDB serves static files from the wwwroot folder.

For example, it can serve files like /css/db.min.css or /js/db.min.js, sending gzip contents if applicable.

As mentioned earlier, ODataDB processes language folders in a specific way.

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

ODataDB supports the following index pages: default.htm, default.html, index.htm, and index.html.

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

Explore ODataDB Endpoints for API and Data Editing

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