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.

Data Sources & Commands

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

When adding a data source, you will specify a name, the database type, and the connection string needed to connect. Since this site is running .NET code, the connection string will need to conform to .NET standards. After adding a data source, you can test it to make sure a connection is successfully established.

The user who adds a new data source is automatically granted access to view and edit its settings. You can grant other admin users access using the Edit Data Source modal.

After you have added a data source and confirmed that it can successfully connect to the database, you can start adding commands. Each command you add becomes an API endpoint that can be called by clients. When adding a command, 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.
  • Direction: An outbound API call entails data being requested from your system and being returned to the client. Typically, this would be a SELECT statement. An inbound API call means the client will be sending data to update your system, either with an INSERT or an UPDATE statement.
  • Type: A command can be either text or stored procedure. This is true regardless of the direction specified
  • Clients: For each command, you can specify which clients have access to it.
  • Command Text: 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 command 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 command text is entered. For SQL Server data sources, a parameter is any value prefixed by '@'. If the data source 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 data sources, commands, clients, or other users. They can grant admin rights to other non-admin users, or lock out other users. Users who have not been granted admin rights can test data sources and commands, as well as view the settings for a command. 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 datasources, commands, and client access, the API is ready to be called by clients. For each command, you can provide the client with the URL and any parameters that need to be passed. For outbound commands, the API call will take the following format:

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

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

POST https://hostname/api/commandname
{ "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
  • 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