Rich Text Descriptions via API

Introduction

Select Star uses rich text descriptions in various parts of the platform, and one of the primary areas where rich text descriptions are used is in the documentation, metrics, and descriptions of metadata objects. These descriptions provide users with a clear and concise explanation of what each object represents and how it can be used. Additionally, rich text descriptions are used to provide context and additional information for tags. This helps users understand how tags are used and what they represent.

Select Star supports both SlateJS and Markdown for formatting text in rich text descriptions. SlateJS library provides a simple and flexible way to create and edit rich text content and provides a wider range of formatting options, including mentions. Whereas with Markdown, it wasn’t possible to create mentions.

Users can now choose the format that best suits their needs when creating and updating rich text descriptions in Select Star. If users have pre-existing documentation expressed in Markdown, syncing it with the Select Star platform will be seamless.

This document will cover how to update rich text descriptions via API using SlateJS and Markdown formats.

Rich Text Descriptions via API Using SlateJS

What is SlateJS?

SlateJS is a JavaScript library that allows you to create and edit rich text content in a web application. It is built on top of React and leverages its component-based architecture. SlateJS provides a rich set of features for formatting text, including headings, lists, tables, links, and media embeds. Additionally, SlateJS allows developers to extend its functionality by creating custom plugins.

SlateJS uses an immutable data structure called a Slate document to represent the rich text content. This document is composed of nodes, which can either be text or other types of content, and marks, which represent the formatting applied to the text.

For more information on SlateJS go to documentation https://docs.slatejs.org/

Supported SlateJS Features

Select Star supports the following SlateJS features for formatting text in rich text descriptions:

text, paragraph, h1, h2, h3, h4, h5, h6, blockquote, ul, ol, code, codeblock, span, link, table, thead, tbody, tr, td, th, and mentions.

These features provide a wide range of options for creating and formatting content, from simple paragraphs to complex tables and mentions of other objects in Select Star. With these features, users can create rich, informative descriptions for documentation, metrics, and metadata objects. Additionally, the ability to use mentions helps users collaborate and communicate effectively within the platform.

Example

To update the rich text description field via API using SlateJS format, you need to send a PATCH request to the API endpoint with the updated content in SlateJS format. Here is an example of a Python script making a request to update a rich text description:

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = "INSERT_METADATA_OBJECT_GUID"

data = {
    "richtext_description": json.dumps([
        {"type": "h1", "children": [{"text": "Description"}]},
        {"type": "paragraph", "children": [{"text": "This is SlateJS description", "bold": True}]}
    ])
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

After making this request, you’ll be able to see this in the Select Star platform as a result:

In this example, we are updating the rich text description with a given GUID with a new H1 header and a paragraph containing the text "This is SlateJS description" in bolded letters. The content is represented in SlateJS format as a JSON object.

Mentions example

Mentions must be placed inside a parent paragraph component. They'll also show in mentioned object's "Mentioned by" section. To mention an object, you need to put its GUID and name into a mention component.

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = ""  # GUID of the object whose description is being updated
mentioned_guid = ""  # GUID of the object that is mentioned
mentioned_name = ""  # Name of the object that is being mentioned

data = {
    "richtext_description": json.dumps([
        [{"type":"paragraph","children":[{"children":[{"text":""}],"mention":{"guid":mentioned_guid,"name":mentioned_name},"type":"mention"}]}]
    ])
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

Ensure the GUID is valid and its associated object exists; otherwise, the mention will be marked as invalid. The "name" field in rich text is used exclusively for plain text relevant to search. In the UI, we'll display the name by pulling the latest data for each mention using its GUID. After this request, you'll see the result on the Select Star platform:

MENTIONED_BY_OBJECT_NAME is linked to MENTION_NAME

Rich Text Descriptions via API Using Markdown

What is Markdown?

Markdown is a lightweight markup language that allows you to create formatted text using plain text syntax. It is commonly used for writing documentation and README files. Markdown provides a simple way to format text, including headings, lists, links, and emphasis. Additionally, Markdown allows developers to extend its functionality by creating custom extensions.

Supported Markdown Features

Select Star supports the following Markdown features for formatting text in rich text descriptions:

text, paragraph, headings (h1 to h6), blockquote, ul, ol, codeblock, link.

These features provide a wide range of options for creating and formatting content, from simple paragraphs to complex lists and codeblocks. With these features, users can create rich, informative descriptions for documentation, metrics, and metadata objects.

Example

To update the rich text description field via API using Markdown format, you need to send a PATCH request to the API endpoint with the updated content in Markdown format. Here is an example of a Python script making a request to update a rich text description:

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = "INSERT_METADATA_OBJECT_GUID"

data = {
    "richtext_description": "## Description\n\n**This is a Markdown description**"
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

After making this request, you’ll be able to see this in the Select Star platform as a result:

In this example, we are updating the rich text description with a given GUID with a new H2 header and a paragraph containing the text "This is a Markdown description" in bolded letters. The content is represented in Markdown format as a string.

Conclusion

In conclusion, Select Star offers two options for formatting text in rich text descriptions: SlateJS and Markdown.

SlateJS provides a wider range of formatting options, including mentions. Users can choose the format that best suits their needs when creating and updating rich text descriptions in Select Star.

SlateJS is a powerful JavaScript library that provides a flexible and easy-to-use way to create and edit rich text content in web applications. However, it is essential to ensure that the new content is in the correct format to avoid rendering failures.

Markdown is a lightweight markup language that provides a simple and intuitive way to format text using plain text syntax. It is easy to learn and use, making it an excellent choice for creating documentation.

Updating rich text descriptions via API using either format requires a PATCH request with the updated content in the appropriate format.