On-premises API

The on-premises API feature provides a way to store workspace data behind your corporate firewall, or using servers anywhere on the Internet, by hosting a local version of the Structurizr API. To use this feature, you need to be subscribed to a paid plan.

A summary of the on-premises API feature

Deployment

The on-premises API is a Java EE web application, packaged as a .war file for deployment into any compatible Java EE server such as Apache Tomcat. A link to download the current version of the on-premises API application can be found on your dashboard. Simply deploy this into an Java EE application server by following the instructions here.

Usage

To use the on-premises API feature, upload an empty workspace to the Structurizr cloud environment that includes a reference to the URL of the on-premises API server that will ultimately store the workspace content. For example, with Java:

Workspace workspace = new Workspace("Name", "Description");
workspace.setApi("https://my-local-server");

StructurizrClient structurizrClient = new StructurizrClient("key", "secret");
structurizrClient.putWorkspace(1234, workspace);

You then upload your real workspace data to your local installation of the on-premises API server.

Workspace workspace = new Workspace("Name", "Description");
// add people, software systems, containers and components
// add views
// add documentation

StructurizrClient structurizrClient = new StructurizrClient("https://my-local-server", "key", "secret");
structurizrClient.putWorkspace(1234, workspace);

The diagrams, documentation and explorations are all implemented on the client-side using JavaScript, which is served from the Structurizr cloud environment. When opening diagrams, documentation or explorations, your web browser will retrieve the workspace content directly from the on-premises API server.

Data storage

The data associated with Structurizr is stored as follows.

Inside your corporate firewall

  • The full workspace content (the JSON representation of your workspace).

Structurizr cloud environment

  • User profile information (e-mail addresses, passwords, etc).
  • Workspace role information (the set of owners, read-write and read-only users).
  • Workspace metadata to support the dashboard (name, description, last updated timestamp and a low resolution thumbnail).

For more information

The source code for the on-premises API is open source and available on GitHub. See the Structurizr API documentation for information about the software architecture, deployment and usage.