Installation Guide

Introduction

This section is dedicated to describe the process of installation and configuration of Platina Standard API (REST) on local, test or production environment. In this guide it is assumed that Platina Standard API will be hosted in IIS despite it is implemented on latest .NET tech stack and supports other hosting alternatives.

Prerequisites

• The server that will host a Platina Standard API should have IIS installed.
• Install the ASP.NET Core Module/Hosting Bundle

Setup SQL Stored Procedure that is required by Platina Standard API

In order the Platina Standard API to operate correctly, it is necessary to install one stored procedure into Platina database:

1. Open SQL Server Management Studio and connect to Platina database.
2. Create a new Query and paste the following stored procedure content in Query Editor:
   

USE [platina]
GO
CREATE OR ALTER PROCEDURE [dbo].[pStructureObjectInfoGet]
	@propID INT
AS
	SELECT [propID], [objectID], [moduleID], [typeID] FROM tObjProperties
	WHERE [propID] = @propID

3. After successful execution, close the SQL Server Management Studio.

Install Platina Standard API

Platina Standard API is shipped as a ZIP-package. When obtained an installation package please follow the next steps:

1. Unpack Platina Standard API ZIP-package to the destination folder.
2. Launch IIS Manager.
3. In IIS Manager choose a web site (e.g. "Default Web Site") where the Platina Standard API application will be hosted:
   
4. Create a new Application for the chosen web site, give it an alias (e.g. "api") and set its' physical path to the folder where Platina Standard API package was extracted:
   
   NOTE: It is not recommended to create an API application as a sub-application of Platina, because this may cause exceptions related to not found references. This is caused because Platina sub-applications inherit configuration of Platina which may be redundant for them.
5. When IIS application for Platina Standard API is created, refer to the next section of this guide that describes configuration.

Configure Platina Standard API

In order the Platina Standard API to function properly, it is required to perform basic configuration steps. The configuration is not complex and is limited by only defining environment variables and setting authentication for the Platina Standard API application in IIS.

Configure Platina Standard API Environment Variables

Platina Standard API configuration is performed by setting corresponding environment variables for the application in IIS. Here is a list of supported environment variables:

Environment Variable	Description	Comment
DB_SERVER	A database server instance that hosts Platina database.	e.g. localhost, platina-db-server
DB_TRUSTED_CONNECTION	Instructs Platina Standard API to use trusted SQL connection when accessing Platina database.	true/false
DB_USER	Used if DB_TRUSTED_CONNECTION is equal to false or not specified. Stores SQL user name to connect to Platina database.	e.g. sa
DB_PASSWORD	Used if DB_TRUSTED_CONNECTION is equal to false or not specified. Stores SQL user password to connect to Platina database.	NOTE: password is stored in unencrypted form in configuration file. So, it is highly recommended to use DB_TRUSTED_CONNECTION whether possible.
PLATINA_API_USERNAME	Represents a user communicating with Platina, this must be a user in platina tUserSettings (e.g. DOMAIN\Administrator). This setting is similar to StandardServiceAuthorizedUser of WCF-based Platina API.
PLATINA_API_BASE_URL	A base URL for Platina Standard API endpoint. It is a URL that consists of IIS website binding and application alias.	e.g. /api if application name is 'api', or /subapp/api if application is nested by some 'subapp' virual path for website.
MAX_BODY_SIZE	The maximum allowed size for HTTP request body in bytes. This limits the size of incoming requests to prevent memory exhaustion.	e.g. 52428800 for 50MB, 104857600 for 100MB, 2147483648 for 2GB as in Platina Web by default

To setup environment variables for Platina Standard API web application follow these steps:

1. In IIS Manager select a Platina Standard API application and select "Configuration Editor" feature:
   
2. In the opened configuration choose system.WebServer/aspNetCore section and expand environmentVariables item:
   
3. Use "Add" button to define new environment variables from the list above:
   
4. When environment variables are defined, do not forget to click "Apply" button to save the changes:
   

Enabling restricted HTTP-verbs

Reason : Enabled WebDAV features blocks some of HTTP verbs used by Standard API

WebDAV features intercept HTTP requests before they reach the API application. WebDAV restricts certain HTTP verbs such as PUT, DELETE, and others that are required by Platina Standard API to function correctly.

Solution: To resolve this issue, you need to remove the WebDAV module and handler from the web.config file of your API application.

1. Open Request Filtering in IIS for API application:

2. Enable PUT, DELETE verbs in Request filtering for the API application:

3. Locate the web.config file in your Platina Standard API application folder (the same location where you configured environment variables).

4. Add the following configuration within the <system.webServer> section:

<system.webServer>
  <modules>
      <remove name="WebDAVModule" /> <!-- add this -->
  </modules>
  <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      <remove name="WebDAV" />  <!-- add this -->
  </handlers>
  <aspNetCore processPath="dotnet" arguments=".\Platina.WebApi.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess">
      <environmentVariables>
          <!-- your database configuration variables -->
      </environmentVariables>
  </aspNetCore>
</system.webServer>

5. After making these changes, restart IIS to apply the configuration.

Note: If the web.config file doesn't exist in your API application folder, create it with the complete configuration shown above.

Configuring Maximum Request Body Size for IIS

When handling large file uploads or data transfers, you need to configure both the API application and IIS to accept larger request bodies. The MAX_BODY_SIZE environment variable (described earlier) sets the limit within the API application, but IIS also has its own restriction that must be configured separately.

Default IIS Limit: IIS restricts request body size to 30,000,000 bytes (~28.6 MB) by default.

When to increase: If you've set MAX_BODY_SIZE to a value higher than 30 MB (e.g., 50 MB, 100 MB, or 2 GB), you must also increase the IIS limit to match or exceed that value. Otherwise, IIS will reject large requests before they reach the API application.

Follow these steps to configure the maximum content length in IIS:

1. Open Request Filtering in IIS for API application:

2. Open Feature Settings:

3. Change the "Maximum allowed content length (Bytes)" value:

Authorization configuration

Since Platina Standard API 8.0.0 api DOES NOT support Windows authentication

It's required to configure appsettings.json properly, see the Authorization guide.

Summary

This guide provides all necessary steps to install and configure Platina Standard API on local, test or production environment. When Platina Standard API is hosted, it exposes built-in Swagger endpoint by the URL: #IIS_API_APPLICATION_URL#/swagger, so for example if API is hosted for default web site with "https" binding in application with alias "api", then Swagger endpoint URL will be: https://SERVER/api/swagger.