Prerequisites

Before installing the SyrinxWebApi, the Syrinx database and system should be updated to the latest version to take advantage of the latest API functionality.  The server should be running IIS (installed with default settings) and should have network connectivity to the Syrinx database server.  The following file generated for the Syrinx database should be supplied and applied prior to installation (accountno is the customer’s specific account number):

• WebAPIApp_accountno.syp- A patch containing the customer’s license for the SyrinxWebApi module.  The patch should be applied to the customer’s database prior to the installation.

This guide will not cover upgrading a Syrinx database or installing IIS.  

Installing the SyrinxWebAPI Web Service

The current version of the SyrinxWebApi installer can be downloaded from the following location:

https://www.syrinxusers.co.uk/Syrinx Web API/SyrinxV4_ApiInstaller.exe

username: download

password: c0nc3pt

Once downloaded, run the installer and press the “Install” button when prompted and then press “Next” on the subsequent installation screen:

The Installer will then begin the installation of the “Microsoft Visual C++ 2015 Redistributable” if not already installed.  It will then prompt the user to install the Microsoft .Net Core 2.2.7 Windows Server Hosting module:

Once those components have been installed the user will then be asked to continue the installation by clicking “Next” and then “Install” or “Upgrade” (if an earlier version is detected) when prompted:

Next, enter the configuration information for the SyrinxWebAPI site and then click “Next” to begin the installation:

The installer will make the appropriate system changes.  When complete, the installer will display URL used to connect to the Swagger utility on the SyrinxWebApi site and will automatically copy this into the clipboard for testing purposes.  Click the “Finish” button to complete the installation:

*Please note that the web server may need to be restarted following the installation of the "Microsoft .NET Core 2.2.7 - Windows Server Hosting" package if it was not previously installed on the web server and was installed during this installation process.

Upon successful completion of the installation, the Web API URL (e.g.: http://localhost/SyrinxWebApi/index.html) presented at the end of the installation should be copied into a web browser such as Chrome, Edge, etc.  If the installation was successful, this should open a “Swagger” page as per the below:

Common Browser Error Codes When Accessing Swagger Page and Causes

HTTP Error 502.5 - Process Failure - Incorrect settings in the appsettings.json configuration file such as DB connection details.   If the defaults were accepted during installation, the appsettings.json configuration will be found in the root of the website directory C:\inetpub\wwwroot\SyrinxWebApi.  For example, named Instances need to be entered as servername\\instancename (backslash characters need to be escaped i.e. \\ instead of \).  

HTTP Error 404.0 - Not Found - Incorrect URL for the Swagger page.  The default is http://localhost/SyrinxWebApi/index.html but can be different depending on the options selected during installation.

HTTP Error 500.21 - Internal Server Error: Handler "aspNetCore" has a bad module "AspNetCoreModule" in its module list – The SyrinxWebAPI relies on the “ASP.NET Core Runtime 2.2.7 hosting bundle”.  If this is not installed, you may get the following error when trying to connect to the Swagger page.  The installer should install this component during installation if it has not been installed already, it can also be downloaded from Microsoft and installed as a stand-alone package.  If installed successfully "aspNetCore" should appear in the “Modules” section of the SyrinxWebApi site in IIS.

Amending Configuration Settings in the Appsettings.json File

As mentioned above, incorrect settings in the configurable areas of the appsettings.json file can cause the SyrinxWebAPI web service to not function correctly.  If there are issues with the site, the appsettings.json file in the root of the SyrinxWebAPI web service directory (e.g.: C:\inetpub\wwwroot\SyrinxWebApi) should be checked to verify that the settings are accurate. Some of the information in the “ConnectionStrings” area of the appsettings.json file are set during the installation using the answers provided on the “Website Configuration” screen of the installer and can be amended manually as follows:

User ID and Password: The site will install with a “User ID” value of “cws” and “Password” value of “x” by default.  The “cws” sql user is normally patched into the Syrinx database/SQL instance when SyrinxWS is installed on a system.  You can check that this user exists and the password details are correct by attempting to connect to the Syrinx SP or Syrinx SP Configuration program with this username and password.  If it does not exist, the service can run under any valid SQL username/password that has been granted access to the Syrinx database.  If this logon information is incorrect, you may see an “Exception in Organisation Service -Login failed for user 'cws'” message in the site’s log files.

Source and Initial Catalog:  These should be set to the Syrinx database name and the name of the server hosting the Syrinx database.  This information can be collected by looking at the existing connection settings for users when they access the Syrinx database via the Syrinx client.  Named instances should be entered as “servername\\instancename” as backslashes require an escape character in .json files (i.e. \\ instead of \).   Database connection settings can also be checked by attempting to establish a 32 bit odbc connection from the web server to the database server using the server/database name values found in the appsettings.json file.

Adding SyrinxWebAPI Username and Passwords
SyrinxWebApi users can be added to the database via the “Logins” menu option in Syrinx SP Configuration\Users:

In later versions of Syrinx, access to specific endpoints of the API can be revoked for a specific user by pressing the “Show Detail” button and then adding the specific endpoints to the “Revoked Endpoints” list: 

Configuring SyrinxWebApi to use SSL/HTTPS

All the steps so far have been related to getting the web service connected using HTTP.  If the customer wishes to use a secure SSL connection via HTTPS, this will require extra IIS configuration.  More specifically it requires an SSL certificate to be requested and the installed in IIS and the bindings for the site to be changed to use HTTPS.  This is not covered in this guide as we cannot ship certificates with the SyrinxWebAPI and the certificate must be issued to and installed by the customer.

Additional Troubleshooting Resources

Logging for SyrinxWebApi can be enabled by manually creating a “logs” folder in SyrinxWebApi’s website directory (e.g. C:\inetpub\wwwroot\SyrinxWebApi\logs if installed to default location) and may provide information on the nature of an error.  The inbuilt windows IIS_IUSRS group should be granted “Modify” security rights on this “logs” folder and its contents.

By default, the API will do minimal logging in the stdout_xxxx_xxxxxxxxxxxxx.log files that it creates.  The API can be set to record more detailed information in those logs by amending the appsettings.json file for the site.  Setting the “Default” value to “Debug” (most detailed) or “Error” (errors only) will increase the amount of information written to the logfiles:

Note – The log files will be much larger with this option enabled so it should be reset to the default “None” setting and/or delete the “logs” folder from the C:\inetpub\wwwroot\SyrinxWebApi\logs directory to completely disable logging once troubleshooting is complete.

The API will also write a “SyrinxWebApi.log” file to the C:\inetpub\wwwroot\SyrinxWebApi\logs directory which can also contain information that may help in troubleshooting issues with the API.  The contents of this logfile can only be viewed by stopping the SyrinxWebApi application pool.