Table of Contents

Management API

How to use our Managment API.

The DynamicWeb Management API is full featured API that can be used to do everything in DynamicWeb 10 that can be done via the UI.

You can access a Swagger test environment on all solutions by adding /admin/api/docs/ to your solutions URL: Management API You can:

  • Query data - e.g. get pages, users, files or any other data model available in the backend
  • Create, update and delete data models - e.g. pages, products, users, etc.
  • Perform commands - e.g. build indexes, start tasks, deactivate users, update prices, set stock levels, etc.

The management API is considered as a 'low-level' API with access to all types of data in DynamicWeb. This means that to use it effectively requires knowledge of the internal structures in DynamicWeb. For example, to create a product in a group and give the product a price you must:

  1. Create the product
  2. Create a relation to the product group
  3. Create a price in the price matrix

So at least 3 different models and commands are needed. You can explore our queries and commands from the backend using the API explorer tool. The API can only be used with a valid API key used as a Authorization bearer token header in the request:

Authorization: Bearer <token>

API Keys

While it's possible to access it with the token for a user, to simplify access an API Key can be generated from the backend using the API Keys tool or via the DynamicWeb CLI and used in place of a user.

The structure of the API Key is <Prefix>.<Key>:

  • The Prefix is used as a hint to what the key is used for, if you ned multiple keys for different scenarios
  • The Key is generated once a request is made to create a new API key

The whole structure is needed when using the key as a bearer token, so a request with the key could look like;

authorization: Bearer myPrefix.ac55ff447173g8e6915a837fwqd22859d91e843535e8cee5697b9b7eb963c8e885ea86049d5a86d5a9e0b76b6f7

The key represents the user creating it, and will as such has the same access they do, see the Permissions documentation for more details.

Query data

All data that's viewable through the DynamicWeb Admin portal is able to be fetched through the Management API.

All of the queries available in your solution can be found in the API Explorer under Settings > System > Developer > API Explorer > Queries and in the Management API swagger documentation that can be found at <yourHost>/admin/api/docs.

Fetching data from the Management API is accessed through GET /Admin/Api/{query}.

There's a different response model depending on the type of Query used and the DataViewModel the Query is based on. If it's a Query that returns a list of items, it will be encapsulated in the data property as the following;

{
  "model": {
    "totalCount": 0,
    "data": [ ] // An array of the DataViewModel used for the Query
  },
  "successful": true,
  "message": ""
}

While if the Query is only returning a single item, that item will be the model property.

{
  "model": { }, // The DataViewModel used for the Query
  "successful": true,
  "message": ""
}

Perform commands

Every action that's done through the DynamicWeb Admin portal is a Command. Just like the queries all of these commands are performed through the Management API, and as such, they can be found under Settings > System > Developer > API Explorer > Commands and in the Management API swagger documentation that can be found at <yourHost>/admin/api/docs.

Performing commands through the Management API is done through POST /Admin/Api/{command}.

There's different kinds of commands, some are based on a DataViewModel and some are not. If they are based on a DataViewModel, the request body should contain that model;

{
  "model": {}
}

A Command can contain properties as well, besides being of a DataViewModel type, these properties are then sent in as separate properties in the request body;

{
  "property1": "",
  "property2": 0,
  "model": {}
}

All bulk action commands will be using an ids property that represents all the ids of the objects that it needs to handle;

{
  "ids": []
}

The response for commands contains the model representing the changed item, if a change is made and the Command was to perform an action on a certain item. However if it's a Command to delete an item or perform some action that doesn't involve a single model, the model property will be null. The status property will tell you if the Command is successfully run with the message "ok". The modelIdentifier will show the id of a newly created object, if the command is one that creates new objects. As such, the response model looks like the following;

{
  "status": "",
  "message": "",
  "exception": "",
  "model": {},
  "modelIdentifier": "",
  "resultActions": []
}

Some commands requires to work on a specific model, in that case the model needs to be specified, this is done through a Query. The Command endpoint has some query parameters to specify the Query it needs to use to find the model to work on;

  • Query.Type - this is the name of the Query to use, i.e GetPageById
  • Query.<Property> - any property the Query might require, i.e id.

In this case the Command will fetch the model based on the Query sent with it, then apply all the changes to that model that is sent in the request bodys model property.

Examples of usage

Update a page

To update an existing page, we will use the Command called PageSave that uses the PageDataModel.

In this example, the Page we want to update has the id 1746. To get the details about this Page, we need to use the Query GetPageById. We can pair this Query up with the Command, so the Command knows what Page it is working on; POST <yourHost>/Admin/Api/PageSave?Query.Id=1746&Query.Type=GetPageById

The request body will then consist of the changes that we want to apply to the Page, so if all we want to do is change the name of the Page, the request body will be the following;

{
  "model": {
    "name": "NewName"
  }
}

The result of this request will be containing the full new updated Page;

{
  "status": "ok",
  "message": "",
  "exception": "",
  "model": {
    "published": false,
    "sort": 19,
    "areaId": 3,
    "parentPageId": 0,
    "pageType": "Swift_Page",
    "id": 1746,
    "created": "2023-05-22T13:08:14.947",
    "updated": "2023-05-22T14:35:52.6498824+02:00",
    ...
  },
  "modelIdentifier": "1746",
  "resultActions": []
}

Delete a page

To delete an existing Page, the PageDelete Command will be used. This is a Command of no type but with one property id which represents the id of the Page to delete.

POST <yourHost>/Admin/Api/PageDelete

{
  "id": 1746
}

The response to this request would be a simple response body;

{
  "status": "ok",
  "message": "",
  "exception": "",
  "model": null,
  "modelIdentifier": null,
  "resultActions": []
}

Build an index

To build an Index, the BuildIndex Command will be used. This Command has a request body that looks like the following;

POST <yourHost>/Admin/Api/BuildIndex

{
  "Repository": "Files",
  "IndexName": "Files.index",
  "BuildName": "Files"
}

The response to this request is like the delete command very simple;

{
  "status": "ok",
  "message": "",
  "exception": "",
  "model": null,
  "modelIdentifier": null,
  "resultActions": []
}

This signifies that the Index build has been started, however it does not mean that is has finished successfully, to see the current status of an Index we need to use the Query IndexStatusByRepositoryAndIndexName that uses the parameters Repository and IndexName;

GET <yourHost>/Admin/Api/IndexStatusByRepositoryAndIndexName?Repository=Files&IndexName=Files.index

{
  "IndexKey": {
    "Repository": "Files",
    "Index": "files.index"
  },
  "State": 0,
  "StateDescription": "All instances are fine",
  "Repository": "Files",
  "IndexName": "files.index",
  "InstanceCount": 2,
  "OnlineInstance": "Files",
  "LastRun": "2023-05-22T16:55:41.1407841",
  "DurationOfBuild": "00:00:00.6997204",
  "Balancer": "LastUpdated",
  "IndexCreatedAt": "2022-10-12T12:01:30.9159723+02:00",
  "BuilderTypeName": "Dynamicweb.Content.Files.FileIndexBuilder, Dynamicweb",
  "PermissionLevel": 1364
}

We see the State is 0 meaning the build went without issues.

Improve this doc
To top