API

This article describes the API end points for Cosmos.

Headless API

When using Cosmos in “Headless” mode, content is published through 3 “article” endpoints and 2 “file” endpoints. An “article” is synonymous with a published “web page.”  File endpoints provide an alternative to the static website as a means of delivering file content to clients.

From the API publisher, you can view the endpoints at the following URL: https://[API DNS address]/Swagger.  Here is an example: https://apicosmosdocs.azurewebsites.net/swagger

Opening the Swagger URL on your API will show the available APIs as shown above. Clicking on an API will give you the chance to try the end point out and see example date being returned.

/api/articles/GetArticle

Method: GET
Retrieves an article, or web page, by its relative URL. It also has an option to not include the layout HTML with the page.

/api/articles/GetLayout

Method: GET
Returns just the website layout.  For a web app, you can make one call to retrieve the layout and reduce the payload of subsequent calls by retrieving articles without the layout.  On the client you would build the web page. REACT applications would be well suited to this approach.

/api/articles/GetTOC

Method: GET
Returns a dynamically generated table of contents for the website.

/api/articles/GetFile

Method: GET
Fetches a file from BLOB storage and returns it with the MIME type information.

/api/articles/GetArticleFolderContents

Method: GET
Retrieves a list of file assets in BLOB storage for a particular article.

Publisher and Editor API

This section lists APIs that are common to both the decoupled publisher and the editor application.

/.well-known/microsoft-identity-association.json

Method: GET
This endpoint is used by Microsoft to validate an Entra ID registered application.  The “ApplicationID” shown below is the same value as the “MicrosoftOAuth__ClientId” set in the web app secrets for Microsoft OAuth settings.
Note: The application IDs for the publisher and editor do not have to be the same.

/Home/CCMS_GetArticleFolderContents/[Url to page]

Method: GET
Retrieves a list of file assets in BLOB storage for a particular article.

/Home/GetTOC?page=&orderByPub=&pageNo=&pageSize

Method: GET
Returns the table of contents for a particular path.  Here are the parameters:

page = URL path to page from which to start.  “/” means start at root.
orderByPub = true or false: Order by publishing date in from latest to oldest.
pageNo = Page number to return.
pageSize = Number of records per page.

/Home/CCMS_POSTCONTACT_INFO

Method: POST
This is where you can have website visitors leave their email address.  The fields that are expected are as follows:
FirstName
LastName
Email (required)
Phone

Note: This endpoint requires the Anti-forgery token to be part of the payload. This helps prevent malicious submissions.  If you post this form with this JavaScript file (/lib/cosmos/forms.js), the token will be automatically added to the payload.

Here is the JavaScript function:

/**
 * Posts a form and adds the Cosmos antiforgery validation token.
 * @param {any} endpoint
 * @param {any} formName
 * @returns {Promise<Response>}
 */
async function ccms___PostForm(endpoint, formName) {

    const form = document.forms[formName];

    const xsrfToken = await ccms___GetXsrfToken();

    return fetch(endpoint, {
        method: "POST",
        headers: {
            RequestVerificationToken: xsrfToken
        },
        body: new FormData(form)
    }).then(data => {
        return data;
    });
}

/ccms__antiforgery/token

Method: GET
This endpoint retrieves an anti-forgery token for use with forms submissions, like the contact list above. See Microsoft documentation for details.

Here is example JavaScript that can retrieve the token:

async function ccms___GetXsrfToken() {
    return fetch("/ccms__antiforgery/token", {
        method: "GET"
    }).then(response => {
        if (!response.ok) {
            throw new Error('Network response was not ok ' + response.statusText);
        }
        const xsrfToken = response.headers.get('XSRF-TOKEN');
        return xsrfToken;
    });
}

/Home/CCMS_GET_POWER_BI_TOKEN?reportId=[GUID]&workspaceId=[GUID]&additionalDataset=[GUID]

Method: GET
This endpoint returns PowerBI embed parameters, that allow the embedding of PowerBI products in web pages.  Use this endpoint with new Power BI V2 workspace experience.

/Home/CCMS_GET_POWER_BI_RDL_TOKEN?reportId=[GUID]&workspaceId=[GUID]

Method: GET
Gets an embed token for a Power BI RDL report.

/Home/CCMS___SEARCH?searchTxt=[search text]

Method: GET
Returns a list of web pages containing the search text.

/[PAGE URL]?mode=json

Method: GET
Adding the parameter “?mode=json” to any decoupled publisher URL will return the web page content as a JSON file instead of rendered HTML.