Help

This site's purpose is to build API endpoints that allow external clients to interact with data on your system. The following information details the components required to make this possible.

Connections, Resources, & Operations

The API endpoints that are accessible to your clients are created by adding connections, resources, and operations to your setup. A connection is a specific database from which your clients will be pulling data, or to which they will be pushing data.

When adding a connection, you will specify a name, the database type, and the connection string needed to connect, along with the user id and password for a database user. Since this site is running .NET code, the connection string will need to conform to .NET standards. (See ConnectionStrings.com for examples.) After adding a connection, you can test it to make sure a connection is successfully established.

The user who adds a new connection is automatically granted access to view and edit its settings. You can grant other admin users access in the Users field when adding or editing a connection. Any users who have not been granted access to a connection will be able to test its connectivity, but they will not be able to see or edit any of its settings.

After you have added a connection and confirmed that it can successfully connect to the database, you can start adding resources and operations to the connection. When adding a resource, you will set the following properties:

  • Name: The name becomes part of the URL used in API calls, so make sure it's short but meaningful, with no spaces.
  • Description: Describe in more detail the purpose of this API endpoint.
  • Clients: For each resource, you can specify which clients have access to it.

Each resource can have one inbound operation and one outbound operation. Those operations become API endpoints that can be called by clients. An outbound operation entails data being requested from your system and being returned to the client. Typically, this would be a SELECT statement. An inbound operation means the client will be sending data to update your system, either with an INSERT or an UPDATE statement.

The following properties must be set on each operation:

  • Type: An operation's SQL can be either text or stored procedure.
  • SQL Query: This is the SQL statement to execute when the API call is triggered. Any valid SQL (or PL/SQL for Oracle) can be defined in this area, including stored procedures if you chose that type.
  • Parameters: Each parameter represents a piece of data that must be passed by the client in the API call. Parameters are automatically determined when the SQL query is entered. For SQL Server connections, a parameter is any value prefixed by '@'. If the connection is an Oracle database, parameters are prefixed by ':'.

Clients

The API endpoints are secured by ensuring that only authenticated requests receive a valid response. Any unauthenticated requests will receive an "Unauthorized" message and the standard 401 status code. To allow clients to authenticate their requests, you add them to the Clients page.

Adding a client only requires providing a client name. An API key is automatically generated for them. You will provide this key to the client so they can include it with their API calls. Once clients are added, you will have the ability to regenerate an API key if needed, or disable their key. Their API key is logged with each API call so you can easily track their activity and troubleshoot possible errors.

Users

Users are the people who have access to this site to view or modify the API settings. Users are added by self-registration. A user must verify their email address before they are allowed to log in to the site.

Users who are granted admin rights can edit the settings for any of the connections, resources, operations, clients, or other users. They can grant admin rights to other non-admin users, lock out, or delete other users. (A user's account must be locked before it can be deleted.) Users who have not been granted admin rights can test connections and resources, as well as view the settings for a resource. Non-admins cannot access the Clients page or the Users page.

When the site is started, an admin user is automatically created with the username 'admin' and a default password. Contact Next Gen support for that password if needed. After you log in with the admin account, it is important to change the email address and password to prevent unauthorized access to your API. You may then choose to grant admin rights to other users and disable the admin account. You will not be able to delete the admin account, however, because it will be added back whenever the site is restarted.

Calling the API

After you have set up your connections, resources, operations, and client access, the API is ready to be called by clients. For each operation, you can provide the client with the URL and any parameters that need to be passed. For outbound operations, the API call will take the following format:

GET https://hostname/api/resourcename?parameter1=value&parameter2=value...

If the operation is inbound, the call should be made as an HTTP POST or PUT, and the parameters are passed in the body as json.

POST https://hostname/api/resourcename
{ "parameter1":"value", "parameter2":"value"...}

In each case, the client's API key needs to be included in the header for the request. The key should be sent as the value for the Authorization header. Without a valid API key, the client will receive an "Unauthorized" response.

Logging

The site uses a tool called NLog for logging. (See nlog-project.org.) Logging configuration settings can be found in the nlog.config file included with the application. Adjustments to the logging level and destination can be made by modifying this configuration file in accord with NLog's documentation.

Change Log
  • 2024.09 UI updates, including upgrades to dependencies
  • 2024.08 Upgraded to support .NET 8; Added ability to import connection settings and to delete a user's account
  • 2024.05 Added ability to export connection settings
  • 2022.02 Bug fixes
  • 2021.12 Verbiage change for connections and resources; Separate user id and password fields for connections; Bug fixes
  • 2021.05 Resolved bug related to displaying actions for less privileged users; Updated Content Security Policies
  • 2020.10 Updated to latest version of jQuery; Added Content Security Policy to header
  • 2020.09 Added support for emailing via SMTP
  • 2020.05 Added screen for managing settings
  • 2020.02 Added license status check and on-screen indications of expiration
  • 2020.01 Initial release