Install the API
On this page
Installing the API package and publishing an API instance are two separate acts. The package installs a template; the Web Configuration tool then creates an IIS site or virtual directory from that template.
After the instance is published, the Admin Center shows its URL in the URL field of the instance's General tab, where a read-only System macro field and two buttons to reconcile the two values appear when the URL and the API Link system macro differ by more than a trailing slash; see API Settings. The API Link system macro is also edited in the Settings App, in its Links group; see Macros Reference.
Before you begin
- You need a Database Access Key for the database the instance uses. The wizard's Database page lists the registered keys and can import one.
- The instance URL must start with
https://. The wizard's URL page accepts no other address.
Install the API package
After the API package is installed, its finish page offers to run the Web Configuration tool, which opens to create an instance from the installed template. The offer is not made in these cases:
- The package is already installed.
- The setup runs as an evaluation installation.
- The installation is an administrative (network-image) installation.
- A major upgrade was detected. In this case the package still runs the tool, which recreates the instances from their saved configuration instead of asking for the settings again.
In an evaluation installation, the Web Configuration tool creates one API instance itself, without showing its wizard, in a fixed virtual directory and bound to a named Database Access Key. When the API package is removed, it removes the instances that were published from its template.
On an upgrade, the package's Files Backup page states that the upgrade
replaces all files and offers to back up the instance files. The backup
check box is selected by default, and the backup folder defaults to a
dated subfolder of Backups\ under the installation directory. Customized
instance files survive only in that backup, with one exception: a hand
edit to the instance's Web.config survives an upgrade when it sits
between the XML comments BEGIN_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048
and END_CUSTOM_EF677073_10AC_44FE_AF1F_2AED27E06048 placed directly under
the root element. After the upgrade, that span is restored at the end of
the root element.
In the Web Configuration tool
To create an instance from the tool itself, choose File > Create > Alloy Navigator API.
Pre-configuration considerations
Configuring an API instance settles four things:
- Database: how the instance connects to the database, by importing a Database Access Key.
- Web: whether the instance is a web site of its own or a virtual directory, and on which site.
- The end-user authentication method of the instance.
- The link macro, API Link, that workflow notifications use to address this instance.
A database holds no API instance settings until the Web Configuration tool writes them when it configures an instance. No page of the wizard sets the API instance's time zone.
Create an instance
When you create an instance, the wizard runs its pages in this order. The Virtual Directory page is skipped when you install the instance as a web site.
- On Database, choose a registered Database Access Key in Key, or click Import Key.... Review SQL Server and Database, and click Next to test the connection.
- On Installation Type, choose Install as a Web site or Install into a virtual directory.
- On the Web Site page, select Choose an existing site: and pick the site, or select Create a new site with the following parameters: and fill in Site Name, IP Address, Host name, Port, and Physical Path.
- If you chose a virtual directory, enter its name and review Physical Path on Virtual Directory. When using an existing site, you can also select a directory already published under it.
- On the Authentication Method page, choose the end-user authentication method. For the choices the page offers, see Publish the Web Applications; for how the methods work, see Authentication Methods.
- On URL, review the generated HTTPS address. If it differs from the
API Link system macro, choose which value to keep:
- Update system macro with instance URL saves the instance URL to the macro when you apply the settings.
- Update instance URL with system macro copies the macro into the URL box.
- On Ready to Apply Settings, review the summary and click Apply. Use Previous to correct a choice before applying it.
For field validation, default folders, and the pages shown in each mode, see The publishing wizard.
When you apply the settings, an empty API Link macro is filled with the instance URL. A macro that already holds a different value is rewritten only when you clicked Update system macro with instance URL on the URL page. You can copy the summary on the last page with Ctrl+C or from its shortcut menu.
Reconfigure an instance
Right-click the instance in the tool's tree and choose Configure, then Full, Database, or Web.
- Full and Database start on the Database page. Web starts on the Installation Type page and skips the Database page.
- A Database run restarts the web application when it applies the settings.
- A reconfigure does not show the URL page. A Full or Web run fills an empty API Link macro but does not change a macro that already holds a value, and a Database run does not change the macro.
- A hand edit to the instance's
Web.configthat sits between the two marker comments survives a reconfigure; the span is moved to the end of the root element. A reconfigure does not redeploy the instance's files, so an edit outside the span also stays, except in the sections the tool itself rewrites.
Check an instance
The tool's tree lists each IIS site that has an http or https binding,
with each application under it named after its virtual directory.
- Select the API instance in the tree. The information pane shows a page
headed "Alloy Navigator API" with Restart and Configure...
buttons and three categories:
- Database - SQL Server, Name, and Access Key.
- Web - Name, URL, Site, Virtual directory (when the instance has one), Physical path, and Authentication.
- Error Logs - "No errors were logged." or "There are some errors logged.", with Clear and View Details, which are unavailable when nothing is logged.
- Read the URL value. The tool builds it from the site binding; on
IIS 7 or later it takes the
httpsbinding when the site has one, otherwise thehttpbinding, without the port when it is 80 forhttpor 443 forhttps, followed by the virtual directory. The host is the binding's host name, else its IP address, and for a binding to all unassigned addresses the computer's DNS host name with its domain. An API published asapion the default HTTPS binding readshttps://<host>/api/. A site served only overhttpon a port other than 80 is also shown with anhttps://URL. - Click the URL to open it in your default browser. Clicking the Physical path value opens the folder in File Explorer.
In the API
Check the default page and service routes
The instance URL answers without credentials with a page headed "Alloy Navigator API" that reads "This is the default page of the" followed by the product name and installed version. The page also shows:
- The authentication in force,
WindowsorAccess Token. - Under Windows authentication, a Username: line, followed by "This user does not have access to the API." when that account fails validation.
- A product documentation link to the online API guide.
The instance also answers these routes, relative to the instance URL, without authentication:
GET lifecycle/healthreturns the product version and a start time in UTC. The start time is recorded the first time the instance's lifecycle routes are used, not when the process starts.POST Ver/GetApiVersionandGET V1/ProductVersionreturn the version of the API application as major, minor, and build number.
A call to one of the API's routes over plain HTTP is answered with status 505 and the message "HTTP protocol is not supported."