Web API (JSON/HTTPS)
Both the cloud and on-premises versions of Structurizr provide a JSON/HTTPS API for getting and putting workspaces, with there currently being client libraries implemented in Java and C#.
The API consists of two endpoints, to get and put a workspace definition respectively.
GET /workspace/{workspaceId}PUT /workspace/{workspaceId}
Authentication/authorisation
Authentication/authorisation of API calls is performed using a HMAC scheme, with the workspace API key and secret pair being used in creating the request.
HTTP headers
GET and PUT requests must include the following HTTP headers.
X-Authorization: The authorisation header, taking the formapiKey:base64(HMAC(apiSecret, messageDigest))(see below).Nonce: A "number once" to prevent reply attacks; for example the current UTC timestamp in milliseconds.
PUT requests must also include the following HTTP headers.
Content-Type: Typically a value ofapplication/json; charset=UTF-8.Content-MD5: A base64 encoded version of the MD5 hash of the workspace definition being sent to the server.
Message digest
The message digest is calculated by appending the following items together, with a newline character (\n) after every item:
- The HTTP verb (i.e.
GETorPUT). - The URI path (e.g.
/workspace/1234). - The MD5 hash of the workspace definition being sent to the server (or the MD5 hash of an empty string,
d41d8cd98f00b204e9800998ecf8427e, for GET requests), as a hex string. - The content type being sent to the server (
application/json; charset=UTF-8for PUT requests, and an empty string for GET requests). - The nonce (e.g. the current UTC timestamp in milliseconds;
1529225966174).
The message digest must then be hashed using the HMAC-SHA256 algorithm, and the result base64 encoded for inclusion into the X-Authorization HTTP header.
The workspace API secret should be used as the key for the HMAC process. The final X-Authorization would look something like this:
caea989b-80a3-4db2-8e5e-7e89be284847:YTQ1NzgxZWQxZjkzYjQwNjk2MzAxNmQ5YTkyODdkZTZlNDEyYjIwZDJhMjc3OWU3MjgxM2RhODE0NzkyMDZlZg==
On receiving the request, the server will check that the workspace ID and API key combination is valid, before calculating its own version of the HMAC message digest based upon the information contained within the HTTP request.
This is then compared with the version submitted in the X-Authorization header, to determine whether the API call is permitted or not.
API rate limiting
To help ensure a fair service to all users, API rate limiting is enforced for all workspace API calls (GET and PUT). See the pricing page for more details.
Workspace JSON schema
An OpenAPI 3.0 specification defining the workspace JSON schema, used when getting or putting a workspace via the API, is defined here (you can import this into the Swagger Editor if needed). Please also see the C4 metamodel for the rules associated with adding elements to views, etc.
openapi: 3.0.0
info:
version: 1.0.0
title: Structurizr
description: The web API for Structurizr.
servers:
- url: https://api.structurizr.com
paths:
'/workspace/{id}':
get:
parameters:
- name: id
in: path
description: The workspace ID.
required: true
schema:
type: string
responses:
'200':
description: A Structurizr workspace.
content:
application/json:
schema:
$ref: "#/components/schemas/Workspace"
put:
parameters:
- name: id
in: path
description: The workspace ID.
required: true
schema:
type: string
requestBody:
description: The workspace to be stored.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
responses:
'200':
description: Updates the workspace.
components:
schemas:
Workspace:
type: object
description: Represents a Structurizr workspace, which is a wrapper for a software architecture model, views, and documentation.
properties:
id:
type: number
format: long
description: The workspace ID.
name:
type: string
description: The name of the workspace.
description:
type: string
description: A short description of the workspace.
version:
type: string
description: A version number for the workspace.
thumbnail:
type: string
description: The thumbnail associated with the workspace; a Base64 encoded PNG file as a Data URI (data:image/png;base64).
lastModifiedDate:
type: string
description: The last modified date, in ISO 8601 format (e.g. "2018-09-08T12:40:03Z").
model:
$ref: '#/components/schemas/Model'
views:
$ref: '#/components/schemas/Views'
documentation:
$ref: '#/components/schemas/Documentation'
Model:
type: object
description: A software architecture model.
properties:
enterprise:
type: object
description: The enterprise associated with this model.
properties:
name:
type: string
description: The name of the enterprise.
people:
type: array
items:
$ref: '#/components/schemas/Person'
softwareSystems:
type: array
items:
$ref: '#/components/schemas/SoftwareSystem'
deploymentNodes:
type: array
items:
$ref: '#/components/schemas/DeploymentNode'
Person:
type: object
description: A person who uses a software system.
properties:
id:
type: string
description: The ID of this person in the model.
name:
type: string
description: The name of this person.
description:
type: string
description: A short description of this person.
tags:
type: string
description: A comma separated list of tags associated with this person.
location:
type: string
description: The location of this person.
enum:
- Extenal
- Internal
- Unspecified
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
items:
$ref: '#/components/schemas/Relationship'
description: The set of relationships from this person to other elements.
SoftwareSystem:
type: object
description: A software system.
properties:
id:
type: string
description: The ID of this software system in the model.
name:
type: string
description: The name of this software system.
description:
type: string
description: A short description of this software system.
location:
type: string
description: The location of this software system.
enum:
- Extenal
- Internal
- Unspecified
tags:
type: string
description: A comma separated list of tags associated with this software system.
containers:
type: array
description: The set of containers within this software system.
items:
$ref: '#/components/schemas/Container'
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
description: The set of relationships from this software system to other
elements.
items:
$ref: '#/components/schemas/Relationship'
Container:
type: object
description: A container (something that can execute code or host data).
properties:
id:
type: string
description: The ID of this container in the model.
name:
type: string
description: The name of this container.
description:
type: string
description: A short description of this container.
technology:
type: string
description: The technology associated with this container (e.g. Apache Tomcat).
tags:
type: string
description: A comma separated list of tags associated with this container.
components:
type: array
description: The set of components within this container.
items:
$ref: '#/components/schemas/Component'
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
description: The set of relationships from this container to other elements.
items:
$ref: '#/components/schemas/Relationship'
Component:
type: object
description: A component (a grouping of related functionality behind an interface that runs inside a container).
properties:
id:
type: string
description: The ID of this component in the model.
name:
type: string
description: The name of this component.
description:
type: string
description: A short description of this component.
technology:
type: string
description: The technology associated with this component (e.g. Spring Bean).
tags:
type: string
description: A comma separated list of tags associated with this component.
code:
type: array
description: The set of code elements that make up this component.
items:
$ref: '#/components/schemas/CodeElement'
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
description: The set of relationships from this component to other elements.
items:
$ref: '#/components/schemas/Relationship'
CodeElement:
type: object
description: Represents a code element (e.g. an interface, a class, a function, etc) that is part of the implementation of a component.
properties:
role:
type: string
description: The role of this code element.
enum:
- Primary
- Supporting
name:
type: string
description: The name of this code element.
type:
type: string
description: The type of the code element (e.g. a fully qualified Java interface or class name).
description:
type: string
description: A short description of this component.
url:
type: string
description: A URL to the source code (e.g. a GitHub repo URL).
language:
type: string
description: The programming language of this code element (e.g. "Java", "C#", etc).
category:
type: string
description: The category of code element; e.g. class, interface, etc.
visibility:
type: string
description: The visibility of the code element; e.g. public, package, private.
size:
type: number
format: integer
description: The size of the code element; e.g. the number of lines.
DeploymentNode:
type: object
description: A deployment node.
properties:
id:
type: string
description: The ID of this deployment node in the model.
name:
type: string
description: The name of this deployment node.
description:
type: string
description: A short description of this deployment node.
technology:
type: string
description: The technology associated with this deployment node (e.g. Apache Tomcat).
instances:
type: number
format: integer
description: The number of instances.
tags:
type: string
description: A comma separated list of tags associated with this deployment node.
children:
type: array
description: The set of child/nested deployment nodes.
items:
$ref: '#/components/schemas/DeploymentNode'
containerInstances:
type: array
description: The set of container instances running in this deployment node..
items:
$ref: '#/components/schemas/ContainerInstance'
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
description: The set of relationships from this deployment node to other elements.
items:
$ref: '#/components/schemas/Relationship'
ContainerInstance:
type: object
description: An instance of a container, running on a deployment node.
properties:
id:
type: string
description: The ID of this container instance in the model.
containerId:
type: string
description: The ID of the container this is an instance of.
instanceId:
type: number
description: The number/index of this instance.
tags:
type: string
description: A comma separated list of tags associated with this container.
properties:
type: object
description: A set of arbitrary name-value properties.
additionalProperties: true
relationships:
type: array
description: The set of relationships from this container to other elements.
items:
$ref: '#/components/schemas/Relationship'
healthChecks:
type: array
description: The set of HTTP-based health checks for this container instance.
items:
$ref: '#/components/schemas/HttpHealthCheck'
HttpHealthCheck:
type: object
description: Describes a HTTP based health check.
properties:
name:
type: string
description: The name of the health check.
url:
type: string
description: The health check URL/endpoint.
interval:
type: number
format: integer
description: The polling interval, in seconds.
timeout:
type: number
format: integer
description: The timeout after which a health check is deemed as failed, in milliseconds.
headers:
type: object
description: A set of name-value pairs corresponding to HTTP headers that should be sent with the request.
additionalProperties: true
Relationship:
type: object
description: A relationship between two elements.
properties:
id:
type: string
description: The ID of this relationship in the model.
description:
type: string
description: A short description of this relationship.
tags:
type: string
description: A comma separated list of tags associated with this relationship.
sourceId:
type: string
description: The ID of the source element.
destinationId:
type: string
description: The ID of the destination element.
technology:
type: string
description: The technology associated with this relationship (e.g. HTTPS, JDBC, etc).
interactionStyle:
type: string
description: The interaction style (synchronous or asynchronous).
enum:
- Synchronous
- Asynchronous
Views:
type: object
description: The set of views onto a software architecture model.
properties:
systemLandscapeViews:
type: array
description: The set of system landscape views.
items:
$ref: '#/components/schemas/SystemLandscapeView'
systemContextViews:
type: array
description: The set of system context views.
items:
$ref: '#/components/schemas/SystemContextView'
containerViews:
type: array
description: The set of container views.
items:
$ref: '#/components/schemas/ContainerView'
componentViews:
type: array
description: The set of component views.
items:
$ref: '#/components/schemas/ComponentView'
dynamicViews:
type: array
description: The set of dynamic views.
items:
$ref: '#/components/schemas/DynamicView'
deploymentView:
type: array
description: The set of deployment views.
items:
$ref: '#/components/schemas/DeploymentView'
filteredViews:
type: array
description: The set of filtered views.
items:
$ref: '#/components/schemas/FilteredView'
configuration:
$ref: '#/components/schemas/Configuration'
SystemLandscapeView:
type: object
description: A system landscape view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
enterpriseBoundaryVisible:
type: boolean
description: Specifies whether the enterprise boundary (to differentiate internal elements from external elements) should be visible on the resulting diagram.
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
SystemContextView:
type: object
description: A system context view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
softwareSystemId:
type: string
description: The ID of the software system this view is associated with.
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
enterpriseBoundaryVisible:
type: boolean
description: Specifies whether the enterprise boundary (to differentiate internal elements from external elements") should be visible on the resulting diagram.
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
ContainerView:
type: object
description: A container view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
softwareSystemId:
type: string
description: The ID of the software system this view is associated with.
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
ComponentView:
type: object
description: A system context view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
containerId:
type: string
description: The ID of the container this view is associated with.
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
DynamicView:
type: object
description: A dynamic view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: An identifier for this view.
elementId:
type: string
description: The ID of the element this view is associated with (optional).
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
DeploymentView:
type: object
description: A deployment view.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
softwareSystemId:
type: string
description: The ID of the software system this view is associated with (optional).
environment:
type: string
description: The name of the environment that this deployment view is for (e.g. "Development", "Live", etc).
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
FilteredView:
type: object
description: Represents a view on top of a view, which can be used to include or exclude specific elements.
properties:
title:
type: string
description: The title of this view (optional).
description:
type: string
description: The description of this view.
key:
type: string
description: A unique identifier for this view.
baseViewKey:
type: string
description: The key of the view on which this filtered view is based.
mode:
type: string
description: Whether elements/relationships are being included or excluded based upon the set of tags.
enum:
- Include
- Exclude
tags:
type: array
description: The set of tags to include/exclude elements/relationships when rendering this filtered view.
items:
type: string
paperSize:
type: string
description: The paper size that should be used to render this view.
enum:
- A6_Portrait
- A6_Landscape
- A5_Portrait
- A5_Landscape
- A4_Portrait
- A4_Landscape
- A3_Portrait
- A3_Landscape
- A2_Portrait
- A2_Landscape
- Letter_Portrait
- Letter_Landscape
- Legal_Portrait
- Legal_Landscape
- Slide_4_3
- Slide_16_9
elements:
type: array
description: The set of elements in this views.
items:
$ref: '#/components/schemas/ElementView'
relationships:
type: array
description: The set of relationships in this views.
items:
$ref: '#/components/schemas/RelationshipView'
ElementView:
type: object
description: An instance of a model element (Person, Software System, Container or Component) in a View.
properties:
id:
type: string
description: The ID of the element.
x:
type: number
format: integer
description: The horizontal position of the element when rendered.
y:
type: number
format: integer
description: The vertical position of the element when rendered.
RelationshipView:
type: object
description: An instance of a model relationship in a View.
properties:
id:
type: string
description: The ID of the relationship.
description:
type: string
description: The description of this relationship (used in dynamic views only).
order:
type: string
description: Gets the order of this relationship (used in dynamic views only; e.g. 1.0, 1.1, 2.0, etc).
vertices:
type: array
description: The set of vertices used to render the relationship.
items:
$ref: '#/components/schemas/Vertex'
position:
type: number
format: integer
description: The position of the annotation along the line; 0 (start) to 100 (end).
Vertex:
type: object
description: The X, Y coordinate of a bend in a line.
properties:
x:
type: number
format: integer
description: The horizontal position of the vertex when rendered.
y:
type: number
format: integer
description: The vertical position of the vertex when rendered.
Configuration:
type: object
description: The configuration associated with a set of views.
properties:
styles:
type: object
description: The styles associated with this set of views.
properties:
elements:
type: array
description: The set of element styles.
items:
$ref: '#/components/schemas/ElementStyle'
relationships:
type: array
description: The set of relationship styles.
items:
$ref: '#/components/schemas/RelationshipStyle'
lastSavedView:
type: string
description: The key of the view that was saved most recently.
defaultView:
type: string
description: The key of the view that should be shown by default.
branding:
$ref: '#/components/schemas/Branding'
terminology:
$ref: '#/components/schemas/Terminology'
Branding:
type: object
description: A wrapper for the font, logo and color scheme associated with a corporate branding.
properties:
logo:
type: string
format: url
description: The URL of an image representing a logo (either a data:uri with base64 encoded content, or a real URL).
font:
type: object
description: Represents a font, including a name and an optional URL for web fonts.
properties:
name:
type: string
description: The font name (e.g. "Times New Roman", "Open Sans", etc).
url:
type: string
format: url
description: For web fonts, the URL where the font can be found.
ElementStyle:
type: object
description: A definition of an element style.
properties:
tag:
type: string
description: The tag to which this element style applies.
width:
type: number
format: integer
description: The width of the element, in pixels.
height:
type: number
format: integer
description: The height of the element, in pixels.
background:
type: string
description: The background colour of the element, as a HTML RGB hex string (e.g. '#ffffff').
color:
type: string
description: The foreground (text) colour of the element, as a HTML RGB hex string (e.g. '#ffffff').
fontSize:
type: number
format: integer
description: The standard font size used to render text, in pixels.
shape:
type: string
description: The shape used to render the element.
enum:
- Box
- RoundedBox
- Circle
- Ellipse
- Hexagon
- Folder
- Cylinder
- Pipe
- WebBrowser
- MobileDevicePortrait
- MobileDeviceLandscape
- Person
- Robot
border:
type: string
description: The type of border used to render the element.
enum:
- Solid
- Dashed
opacity:
type: number
format: integer
description: The opacity used when rendering the element; 0-100.
metadata:
type: boolean
description: Whether the element metadata should be shown or not.
description:
type: boolean
description: Whether the element description should be shown or not.
RelationshipStyle:
type: object
description: A definition of a relationship style.
properties:
tag:
type: string
description: The tag to which this relationship style applies.
thickness:
type: number
format: integer
description: The thickness of the line, in pixels.
color:
type: string
description: The colour of the line, as a HTML RGB hex string (e.g. '#ffffff').
fontSize:
type: number
format: integer
description: The standard font size used to render the relationship annotation, in pixels.
width:
type: number
format: integer
description: The width of the relationship annotation, in pixels.
dashed:
type: boolean
description: A flag to indicate whether the line is rendered as dashed or not.
routing:
type: string
description: The routing algorithm used when rendering lines.
enum:
- Direct
- Orthogonal
position:
type: number
format: integer
description: The position of the annotation along the line; 0 (start) to 100 (end).
opacity:
type: number
format: integer
description: The opacity used when rendering the line; 0-100.
Documentation:
type: object
description: The documentation associated with this software architecture model.
properties:
sections:
type: array
items:
$ref: '#/components/schemas/DocumentationSection'
decisions:
type: array
items:
$ref: '#/components/schemas/Decision'
images:
type: array
items:
$ref: '#/components/schemas/Image'
template:
$ref: '#/components/schemas/DocumentationTemplateMetadata'
DocumentationSection:
type: object
description: A documentation section.
properties:
title:
type: string
description: The title (name/section heading) of the section.
content:
type: string
description: The Markdown or AsciiDoc content of the section.
format:
type: string
description: The content format type.
enum:
- Markdown
- AsciiDoc
order:
type: number
format: integer
description: The order (index) of the section in the document.
elementId:
type: string
description: The ID of the element (in the model) that this section applies to (optional).
Decision:
type: object
description: A decision record (e.g. architecture decision record).
properties:
id:
type: string
description: The ID of the decision.
date:
type: string
description: The date that the decision was made (ISO 8601 format).
status:
type: string
description: The status of the decision.
enum:
- Proposed
- Accepted
- Superseded
- Deprecated
- Rejected
title:
type: string
description: The title of the decision.
content:
type: string
description: The Markdown or AsciiDoc content of the section.
format:
type: string
description: The content format type.
enum:
- Markdown
- AsciiDoc
elementId:
type: string
description: The ID of the element (in the model) that this decision applies to (optional).
Image:
type: object
description: Represents a base64 encoded image (png/jpg/gif).
properties:
name:
type: string
description: The name of the image.
content:
type: string
description: The (base64 encoded) content of the image.
type:
type: string
description: The image MIME type (e.g. "image/png").
DocumentationTemplateMetadata:
type: object
description: Information about the documentation template used to create the documentation.
properties:
name:
type: string
description: The name of the documentation template.
author:
type: string
description: The name of the author of the documentation template.
url:
type: string
format: url
description: A URL that points to more information about the documentation template.
Terminology:
type: object
description: Provides a way for the terminology on diagrams, etc to be modified (e.g. language translations).
properties:
enterprise:
type: string
description: The terminology used when rendering the enterprise boundary.
person:
type: string
description: The terminology used when rendering people.
softwareSystem:
type: string
description: The terminology used when rendering software systems.
container:
type: string
description: The terminology used when rendering containers.
component:
type: string
description: The terminology used when rendering components.
code:
type: string
description: The terminology used when rendering code elements.
deploymentNode:
type: string
description: The terminology used when rendering deployment nodes.