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:
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:
- Create the product
- Create a relation to the product group
- 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 Dynamic
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.eGetPageById
- Query.<Property> - any property the
Query
might require, i.eid
.
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.