Creating Apps That Use Microservices

Overview

DNN provides APIs that you can use to access the microservices from your app. Essentially, your app simply needs to generate HTTPS requests with specific information in the URL path, the URL query, or the body of the message, along with an authentication token in the header. The results are sent back in the body of the message from the server.

Each microservice has several groups of APIs related to each other.

Structured Content has groups for content types, content items, published content items, the visualizer engine, visualizer definitions, and visualizer instances.
Form Builder has groups for campaigns, form templates (forms), form template user preferences, and form responses.

Each API is an action: GET, POST, PUT, or DELETE. Example: The ContentTypes group under the Structured Content microservice allows you to do the following:

GET to retrieve the list of all items or specific item
POST to create a new item
PUT to update an existing item
DELETE to remove an existing item

An item might be a content type, a content item, a visualizer, a visualizer instance, a campaign, a form, a form response, or a set of user preferences for a form.

Parameters and Results

The microservices expect the parameters of a microservice API in one of these locations:

URL path. If the API retrieves (GET), modifies (PUT), or deletes (DELETE) a specific item, the ID of the item is typically added to the URL path.
URL query. If the API retrieves (GET) a list of items, according to a set of criteria, the criteria are specified as optional key-value pairs in the query portion of a URL.
Message body. If the API creates (POST) an item, the properties of the new item are specified in a JSON-serialized data transfer object (DTO) in the body of the request. The fields in a DTO vary depending on the item type.

If the API returns an item or a list of items, the result is a JSON-serialized DTO in the body of the response.

Getting the Item ID

Each item has a unique ID that identifies it, regardless of its type. Many of the APIs require the ID of the specific item to act on.

You can determine the ID of a specific item by performing a filtered GET. Example: The GET /api/FormTemplates API returns a JSON-formatted list that match the criteria specified in the URL query. Each element of the resulting list includes a pair with the key id.

Example

This example updates a content item using the PUT /api/ContentItems/{id} API, which takes three parameters:

id. (string) Required in the path.
contentItem. (JSON-formatted string) Required as the request body.
publish. (boolean) Optional parameter in the URL query.

If you don't know the content item's ID, use GET /api/ContentItems with parameters that match the criteria you want. Then find the content item you want from the returned list. The returned list of content item objects will be in this format:


    {
        "documents": [
            {
                "id": "11111111-...",
                "contentTypeId": "myContentType",
                "contentTypeName": "myContentType",
                "name": "myContentItemName",
                "description": "string",
                "language": "string",
                "alreadyPublished": true,
                "details": {},
                "currentVersion": 0,
                "usages": 0,
                "createdAt": "string",
                "createdBy": {
                    "id": "string",
                    "name": "string",
                    "thumbnail": "string"
                },
                "updatedAt": "string",
                "updatedBy": "StructuredContent.Models.UserInfo",
                "stateId": 0,
                "tags": [
                    "tag1", "tag2", "tag3"
                ],
                "clientReferenceId": "string"
            },
            {
                "id": "22222222-...",
                ...
            },
            {
                "id": "33333333-...",
                ...
            }
            ...
        ],
        "totalResultCount": "string"
    }

If you know the content item's ID, use GET /api/ContentItems/{id}. The returned content item object will be in this format:


    {
        "id": "11111111-...",
        "contentTypeId": "string",
        "contentTypeName": "string",
        "name": "string",
        "description": "string",
        "language": "string",
        "alreadyPublished": true,
        "details": {},
        "currentVersion": 0,
        "usages": 0,
        "createdAt": "string",
        "createdBy": {
            "id": "string",
            "name": "string",
            "thumbnail": "string"
        },
        "updatedAt": "string",
        "updatedBy": "StructuredContent.Models.UserInfo",
        "stateId": 0,
        "tags": [
            "tag1", "tag2", "tag3"
        ],
        "clientReferenceId": "string"
    }

Copy the values from the returned content item object and paste them to the body of your own PUT request. Then replace the values you want to change. The body parameter must be in this format:


    {
        "id": "11111111-...",
        "contentTypeId": "string",
        "contentTypeName": "string",
        "name": "My New Name",
        "description": "My new description goes here.",
        "language": "string",
        "alreadyPublished": true,
        "details": {},
        "currentVersion": 0,
        "usages": 0,
        "createdAt": "string",
        "createdBy": {
            "id": "string",
            "name": "string",
            "thumbnail": "string"
        },
        "updatedAt": "string",
        "updatedBy": "StructuredContent.Models.UserInfo",
        "stateId": 0,
        "tags": [
            "tag1", "tag2", "tag3", "my new tag"
        ],
        "clientReferenceId": "string"
    }

Note: You cannot change the ID.

Construct the URL of your PUT request to contain the path parameter (id) and the optional query parameter (publish). Example: If id is "11111111-1111-1111" and you want the changes to be published immediately, then the URL would be as follows:
```
    https://example.com/api/ContentItems/11111111-1111-1111?publish=true
                    
```

Remember: Include the authentication token in the header.