Skip to main content

Getting Started with ClassCAD API Wrappers

This guide will help you set up and run your first ClassCAD application using our API wrappers for Node.js, Python, or .NET.

Prerequisites​

Before you begin, make sure you have:

  • Node.js >= 20 (for SocketIO server mode and Node.js examples)
  • Python 3.x (for Python examples)
  • .NET 8.0 or higher (for .NET examples)

Step 1: Download and Install ClassCAD​

Download ClassCAD from the Downloads page and extract it to a directory of your choice.

mkdir classcad
cd classcad
# Install ClassCAD here

Step 2: Start ClassCAD​

Open a terminal and launch ClassCAD in SocketIO server mode:

cd classcad
classcad-socketio.cmd
tip

Don't forget to provide your ClassCAD Key when starting ClassCAD!

note

The ClassCAD SocketIO server runs as a Node.js process, which is why Node.js >= 20 is required regardless of your chosen API language.

Step 3: Install API Wrappers​

Choose your preferred programming language and install the corresponding API wrappers.

info

Get the exact download URLs for your ClassCAD version from the Downloads page under "API Wrappers". The API wrapper packages are self-hosted and installed directly via URL rather than through a public registry (npm/PyPI/NuGet). This gives us more control over distribution.

Node.js / npm​

mkdir my-classcad-project
cd my-classcad-project
npm init -y
npm i <API_JS_URL>
npm i <API_JS_CONNECTOR_URL>

Python / pip​

mkdir my-classcad-project
cd my-classcad-project
python -m venv .venv
.venv\Scripts\activate.bat
pip install <API_PY_URL>
pip install <API_PY_CONNECTOR_URL>

.NET / NuGet​

mkdir my-classcad-project
cd my-classcad-project

# Download packages (use URLs from Downloads page)
curl -o ClasscadApi.nupkg <API_CS_URL>
curl -o ClasscadConnector.nupkg <API_CS_CONNECTOR_URL>

# Create a new project if you don't have one
dotnet new console -f net8.0 --force

# Configure local NuGet source
New-Item nuget.config -ItemType File -Force
'<?xml version="1.0" encoding="utf-8"?><configuration></configuration>' | Set-Content nuget.config -Encoding UTF8
dotnet nuget add source https://api.nuget.org/v3/index.json --name nuget.org --configfile nuget.config
dotnet nuget add source . --name local --configfile nuget.config

# Install packages
dotnet add package ClasscadApi --prerelease
dotnet add package ClasscadConnector --prerelease
dotnet restore
rm *.nupkg
info

The .NET examples require a local NuGet source because the packages are downloaded manually. The connector package has dependencies from nuget.org, which is why both sources need to be configured.

Step 4: Write Your First Application​

Node.js Example​

Create main.js:

const { SocketIOClient } = require('@classcad/api-js-connector')

const main = async () => {
  const client = new SocketIOClient({ url: 'ws://127.0.0.1:9091' })
  try {
    await client.connect()
    const api = client.getApiU()
    const part = await api.v1.part.create({ name: 'My First Part' })
    console.info(part)
  } catch (error) {
    console.error(error)
  }
  client.close()
}

main()

Run it:

node main.js

Python Example​

Create main.py:

import asyncio
from classcadconnector import *


async def main():
    client = SocketIOClient(url="ws://127.0.0.1:9091")

    try:
        await client.connect()
        api = client.getApiU()

        part = await api.v1.part.create({"name": "My First Part"})

        print(part)

    except Exception as error:
        print(error)

    finally:
        await client.close()


if __name__ == "__main__":
    asyncio.run(main())

Run it:

python main.py

.NET Example​

Update Program.cs:

var client = new ClassCAD.SocketIOClient("ws://127.0.0.1:9091");
try
{
    await client.Connect();
    var api = client.GetApiU();
    var part = await api.v1.part.Create(new() { name = "Part1" });
    Console.WriteLine(part);
}
catch (Exception error)
{
    Console.Error.WriteLine(error);
}
client.Close();

Run it:

dotnet run

Understanding the Example​

The example demonstrates the basic workflow:

  1. Create a SocketIO Client: The client handles communication with ClassCAD via WebSocket
  2. Connect to ClassCAD: Establish a connection to the running ClassCAD instance
  3. Get the API: Use getApiU() to access the unwrapped API (returns direct results, throws exceptions on errors)
  4. Call API Methods: Access the API through the versioned namespace (e.g., api.v1.part.create())
  5. Handle Results: Process the results or catch errors
  6. Close the Connection: Always close the client when done
Wrapped vs Unwrapped API
  • Unwrapped API (getApiU()): Returns direct results, throws exceptions on errors - best for most use cases
  • Wrapped API (getApi()): Returns full JSON response with result and messages (errors, warnings, and infos arrays) - useful when you need detailed message handling

API Architecture​

ClassCAD provides different APIs for different use cases:

  • Solid API: For programmatic solid geometry creation (extrusions, revolutions, Boolean operations)
  • Part API: For feature-based modeling with operation history
  • Assembly API: For constraint-based assembly construction
  • Sketch API: For parametric 2D sketches with constraints
  • Curve API: For advanced curve creation (Bezier, interpolation, polylines)
  • Drawing API: For creating 2D drawings from 3D models
  • Common API: Core functionality for file operations, imports/exports, and shared utilities

All APIs follow standardized design principles:

  • JSON Parameters: All methods accept a single JSON object parameter
  • Result & Error Handling: When using the wrapped client helpers (getApi()), each API call returns an object with both result and messages properties. In contrast, the unwrapped APIs (getApiU()) return direct results and throw on errors.

Next Steps​

Now that you have a running example, you can:

  • Explore specific API usage examples in this section
  • Check out the API Reference for detailed documentation
  • Learn about different use cases
  • Understand the architecture behind ClassCAD

Troubleshooting​

Connection Failed:

  • Make sure ClassCAD is running in SocketIO server mode (started according to your platform's instructions)
  • Verify the port (default is 9091)
  • Check your firewall settings

License Error:

  • Ensure you've provided a valid ClassCAD Key when starting ClassCAD

Package Installation Issues:

  • For .NET: Make sure you've configured both nuget.org and the local source
  • For Python: Activate your virtual environment before installing packages
  • For Node.js: Use Node.js version 20 or higher