Glossary Terms

The Konigle SDK provides comprehensive glossary term management for creating and managing terminology definitions. Glossary terms support rich EditorJS content, SEO metadata, author attribution, and help build comprehensive knowledge bases.

Creating Glossary Terms

Basic Glossary Term Creation

import konigle

client = konigle.Client(api_key="your-api-key")

# Create a simple glossary term
term_data = konigle.models.GlossaryTermCreate(
    title="Application Programming Interface",
    name="API",
    handle="api",
    summary="A set of protocols, routines, and tools for building software applications",
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "header1",
                "type": "header",
                "data": {"text": "What is an API?", "level": 2}
            },
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {
                    "text": "An Application Programming Interface (API) is a set of protocols, routines, and tools that allows different software applications to communicate with each other."
                }
            }
        ],
        "version": "2.28.2"
    },
    folder="glossary_folder_tech"
)

term = client.glossary_terms.create(term_data)
print(f"Created glossary term: {term.id}")

Term with Auto-generated Handle

# Handle will be auto-generated from title if not provided
term_data = konigle.models.GlossaryTermCreate(
    title="Machine Learning",
    name="Machine Learning (ML)",
    summary="A method of data analysis that automates analytical model building using algorithms that iteratively learn from data",
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {"text": "Machine learning is a branch of artificial intelligence that focuses on building applications that learn from data and improve their accuracy over time without being programmed to do so."}
            }
        ],
        "version": "2.28.2"
    },
    folder="glossary_folder_ai"
)

term = client.glossary_terms.create(term_data)
print(f"Auto-generated handle: {term.handle}")

Term with Rich Content

# Create glossary term with comprehensive EditorJS content
term_data = konigle.models.GlossaryTermCreate(
    title="Representational State Transfer",
    name="REST",
    handle="rest",
    summary="REST is an architectural style that defines a set of constraints for creating web services",
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "header1",
                "type": "header",
                "data": {"text": "What is REST?", "level": 2}
            },
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {
                    "text": "REST (Representational State Transfer) is an architectural style that defines a set of constraints and properties based on HTTP."
                }
            },
            {
                "id": "principles_header",
                "type": "header",
                "data": {"text": "Key Principles", "level": 3}
            },
            {
                "id": "principles_list",
                "type": "list",
                "data": {
                    "style": "unordered",
                    "items": [
                        "Stateless communication between client and server",
                        "Uniform interface for resource identification",
                        "Client-server architecture separation",
                        "Cacheable responses when appropriate",
                        "Layered system architecture"
                    ]
                }
            },
            {
                "id": "quote1",
                "type": "quote",
                "data": {
                    "text": "REST is not a protocol or a standard, but rather a set of architectural constraints.",
                    "caption": "Roy Fielding"
                }
            }
        ],
        "version": "2.28.2"
    },
    folder="glossary_folder_web"
)

term = client.glossary_terms.create(term_data)
print(f"Comprehensive glossary term created: {term.title}")

Term with SEO Metadata

from konigle.models import SEOMeta

# Create glossary term with complete SEO optimization
term_data = konigle.models.GlossaryTermCreate(
    title="Software as a Service",
    name="SaaS",
    handle="saas",
    summary="SaaS is a software distribution model where applications are hosted by a service provider and made available over the internet",
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {"text": "Software as a Service (SaaS) is a software distribution model in which applications are hosted by a vendor or service provider and made available to customers over a network, typically the Internet."}
            }
        ],
        "version": "2.28.2"
    },
    seo_meta=SEOMeta(
        title="SaaS Definition - Software as a Service | Tech Glossary",
        description="Learn what SaaS (Software as a Service) means, its benefits, and how it differs from traditional software delivery models",
        keywords="saas,software as a service,cloud computing,software delivery,subscription software"
    ),
    json_ld={
        "@context": "https://schema.org",
        "@type": "DefinedTerm",
        "name": "SaaS",
        "alternateName": "Software as a Service",
        "definition": "A software distribution model where applications are hosted by a service provider and made available over the internet",
        "inDefinedTermSet": "Technology Glossary"
    },
    folder="glossary_folder_business"
)

term = client.glossary_terms.create(term_data)
print(f"SEO-optimized glossary term created: {term.title}")

Term with Author and Collaboration

# Create glossary term with author and contributors
term_data = konigle.models.GlossaryTermCreate(
    title="Development and Operations",
    name="DevOps",
    handle="devops",
    summary="DevOps is a set of practices that combines software development and IT operations to shorten the development lifecycle",
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {"text": "DevOps is a cultural and technical movement that emphasizes communication, collaboration, integration, and automation between software developers and IT operations professionals."}
            }
        ],
        "version": "2.28.2"
    },
    folder="glossary_folder_development",
    author="author_123456789",
    contributor_ids=["author_111", "author_222"],
    reviewer_ids=["author_333"],
    show_author=True
)

term = client.glossary_terms.create(term_data)
print(f"Collaborative glossary term created: {term.title}")

Listing Glossary Terms

Basic Term Listing

# List all glossary terms with pagination
terms = client.glossary_terms.list(page=1, page_size=20)

print(f"Total terms: {terms.count}")
print(f"Current page: {terms.current_page}")
print(f"Total pages: {terms.total_pages}")

for term in terms.payload:
    print(f"- {term.title}")
    print(f"  Handle: {term.handle}")
    print(f"  Summary: {term.summary[:100]}...")
    print(f"  Published: {term.published}")

Filtering Glossary Terms

from konigle.filters.website import GlossaryTermFilters

# Using filter object
term_filters = GlossaryTermFilters(
    q="api",  # Search in title and name
    published=True,
    ordering="name"  # Sort alphabetically by name
)

filtered_terms = client.glossary_terms.list(
    page=1,
    page_size=10,
    filters=term_filters
)

# Filter published terms
published_terms = client.glossary_terms.list(
    filters=GlossaryTermFilters(published=True, ordering="-created_at")
)

# Search terms by content
search_results = client.glossary_terms.list(
    filters=GlossaryTermFilters(q="machine learning")
)

# Get terms alphabetically
alphabetical_terms = client.glossary_terms.list(
    filters=GlossaryTermFilters(ordering="name")
)

Getting a Specific Glossary Term

# Get glossary term by ID
term = client.glossary_terms.get("term_123456789")
print(f"Term: {term.title}")
print(f"Definition: {term.summary}")
print(f"Author: {term.author}")
print(f"Folder: {term.folder}")
print(f"Contributors: {len(term.contributors)}")
if term.published_at:
    print(f"Published: {term.published_at}")

Updating Glossary Terms

# Update term metadata
update_data = konigle.models.GlossaryTermUpdate(
    title="Updated API Definition",
    summary="An updated and comprehensive definition of APIs including modern REST and GraphQL standards"
)

updated_term = client.glossary_terms.update("term_123456789", update_data)
print(f"Updated term: {updated_term.title}")

# Update term content
content_update = konigle.models.GlossaryTermUpdate(
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "id": "header1",
                "type": "header",
                "data": {"text": "Updated Definition", "level": 2}
            },
            {
                "id": "paragraph1",
                "type": "paragraph",
                "data": {
                    "text": "This definition has been updated to reflect current industry standards and best practices."
                }
            },
            {
                "id": "paragraph2",
                "type": "paragraph",
                "data": {
                    "text": "Modern APIs include REST, GraphQL, and gRPC implementations with enhanced security and performance features."
                }
            }
        ],
        "version": "2.28.2"
    }
)

term_with_new_content = client.glossary_terms.update("term_123456789", content_update)

# Update collaborators
collaboration_update = konigle.models.GlossaryTermUpdate(
    contributor_ids=["author_111", "author_222", "author_444"],
    reviewer_ids=["author_333", "author_555"],
    show_author=True
)

collaborative_term = client.glossary_terms.update("term_123456789", collaboration_update)

Deleting Glossary Terms

# Delete a glossary term
client.glossary_terms.delete("term_123456789")
print("Glossary term deleted successfully")

Glossary Actions

Publishing and Unpublishing Glossary Terms

# Publish a glossary term to make it live on your website
term = client.glossary_terms.get("term_123456789")
published_term = term.publish()
print(f"Glossary term published: {published_term.published}")
print(f"Published at: {published_term.published_at}")

# Or use the manager directly
published_term = client.glossary_terms.publish("term_123456789")

# Unpublish a glossary term to take it offline
unpublished_term = term.unpublish()
print(f"Glossary term unpublished: {unpublished_term.published}")

# Or use the manager directly
unpublished_term = client.glossary_terms.unpublish("term_123456789")

Changing Glossary Term Handles

# Change a glossary term's URL handle
term = client.glossary_terms.get("term_123456789")

# Change handle without redirect
updated_term = term.change_handle("new-term-handle")
print(f"New handle: {updated_term.handle}")

# Change handle with redirect from old URL
updated_term = term.change_handle("better-handle", redirect=True)
print(f"Handle changed to: {updated_term.handle}")
print("Redirect created from old handle")

CLI Usage

Use the CLI for quick glossary management:

# Create term with content file
konigle glossary create \
  --title "Application Programming Interface" \
  --name "API" \
  --summary "Set of protocols for building software applications" \
  --content-file ./sample-blog-content.json \
  --author "author_123" \
  --folder "glossary_folder_tech"

# Create term with inline content JSON
konigle glossary create \
  --title "REST API" \
  --content '{"blocks":[{"type":"paragraph","data":{"text":"RESTful web service definition"}}]}'

# List terms
konigle glossary list --page 1 --page-size 20
konigle glossary list --published

# Get specific term
konigle glossary get term_123456789

# Update term
konigle glossary update term_123456789 \
  --title "Updated API Definition" \
  --content-file ./updated-content.json

# Delete term
konigle glossary delete term_123456789 --yes

Working with Glossary Collections

Creating Term Collections by Topic

def create_tech_glossary():
    """Create a collection of technology terms."""

    tech_terms = [
        {
            "name": "API",
            "title": "Application Programming Interface",
            "summary": "Set of protocols for building software applications"
        },
        {
            "name": "REST",
            "title": "Representational State Transfer",
            "summary": "Architectural style for designing web services"
        },
        {
            "name": "JSON",
            "title": "JavaScript Object Notation",
            "summary": "Lightweight data interchange format"
        }
    ]

    created_terms = []

    for term_info in tech_terms:
        term_data = konigle.models.GlossaryTermCreate(
            name=term_info["name"],
            title=term_info["title"],
            summary=term_info["summary"],
            content={
                "time": 1672531200000,
                "blocks": [
                    {
                        "id": "definition",
                        "type": "paragraph",
                        "data": {"text": term_info["summary"]}
                    }
                ],
                "version": "2.28.2"
            },
            folder="glossary_folder_tech",
            seo_meta=SEOMeta(
                title=f"{term_info['title']} Definition | Tech Glossary",
                description=f"Learn about {term_info['title']}: {term_info['summary']}"
            )
        )

        term = client.glossary_terms.create(term_data)
        created_terms.append(term)
        print(f"Created: {term.title}")

    return created_terms

# Usage
tech_terms = create_tech_glossary()
print(f"Created {len(tech_terms)} technology terms")

Loading Content from File

import json

# Load EditorJS content from file
with open("glossary-content.json", "r") as f:
    content_data = json.load(f)

term_data = konigle.models.GlossaryTermCreate(
    title="Term from File",
    name="term-from-file",
    content=content_data,
    summary="Glossary term created from external content file",
    folder="glossary_folder_general"
)

term = client.glossary_terms.create(term_data)

Async Operations

import asyncio

async def manage_glossary_terms():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create glossary term
        term_data = konigle.models.GlossaryTermCreate(
            title="Async Term",
            name="async-term",
            summary="Created using async operations",
            folder="glossary_folder_tech"
        )
        term = await client.glossary_terms.create(term_data)

        # List terms
        terms = await client.glossary_terms.list(page_size=10)

        # Update term
        update_data = konigle.models.GlossaryTermUpdate(title="Updated Async Term")
        updated_term = await client.glossary_terms.update(term.id, update_data)

        # Delete term
        await client.glossary_terms.delete(term.id)

asyncio.run(manage_glossary_terms())

Best Practices

SEO-Optimized Terms

from konigle.models.website.base import SEOMeta

def create_seo_optimized_term(name: str, title: str, definition: str, keywords: list):
    """Create an SEO-optimized glossary term."""
    keyword_string = ",".join(keywords)

    return konigle.models.GlossaryTermCreate(
        name=name,
        title=title,
        summary=definition,
        content={
            "time": 1672531200000,
            "blocks": [
                {
                    "id": "definition",
                    "type": "paragraph",
                    "data": {"text": definition}
                }
            ],
            "version": "2.28.2"
        },
        seo_meta=SEOMeta(
            title=f"{title} Definition | Glossary",
            description=f"Learn about {title}: {definition}",
            keywords=keyword_string
        ),
        json_ld={
            "@context": "https://schema.org",
            "@type": "DefinedTerm",
            "name": name,
            "alternateName": title if title != name else None,
            "definition": definition,
            "inDefinedTermSet": "Company Glossary"
        }
    )

Content Templates

def create_acronym_term(acronym: str, full_form: str, definition: str):
    """Create a glossary term for acronyms."""
    return konigle.models.GlossaryTermCreate(
        name=acronym,
        title=f"{acronym} - {full_form}",
        summary=f"{acronym} stands for {full_form}. {definition}",
        content={
            "time": 1672531200000,
            "blocks": [
                {
                    "id": "header1",
                    "type": "header",
                    "data": {"text": f"{acronym} - {full_form}", "level": 2}
                },
                {
                    "id": "definition",
                    "type": "paragraph",
                    "data": {"text": definition}
                }
            ],
            "version": "2.28.2"
        }
    )

# Usage
crud_term = create_acronym_term(
    acronym="CRUD",
    full_form="Create, Read, Update, Delete",
    definition="The four basic operations that can be performed on data in most applications."
)

Glossary terms provide a powerful way to create and manage terminology definitions with full SEO optimization, collaboration features, and flexible EditorJS-based content structure.