Skip to content

Developer Documentation

Jump to bottom
AZIRAR Mhamed (SNCF / DGA NUMERIQUE / e.SNCF Sol.D2D DDSP IDFCE) edited this page Apr 22, 2026 · 2 revisions

Developer Documentation | Nodify Headless CMS

Nodify is an open source headless CMS built with Java, designed specifically for developers. It separates content management from the front-end, offering complete flexibility via RESTful APIs. This document serves as a technical reference for interacting with the Nodify API, managing content, tracking analytics, and creating dynamic pages with templates — all with built-in i18n (internationalization) support.

1. Getting Started and Installation

Get Nodify up and running quickly using Docker. The project is open source and available on GitHub.

git clone https://github.com/AZIRARM/nodify.git
cd nodify
docker compose up -d

Requirements:

  • Docker & Docker Compose
  • Java runtime (for local development)

2. CaaS (Content as a Service) Compatibility

Nodify is fully compatible with CaaS (Content as a Service) architecture. This means your content is delivered via API to any frontend or application, completely decoupled from the presentation layer. Nodify supports duplex communication (bidirectional real-time data exchange), enabling live content updates and real-time synchronization across all your clients.

Key CaaS Features:

  • API-first design – Content delivered as pure data (JSON, XML, HTML)
  • Real-time duplex communication – Bidirectional data flow between server and clients
  • Multi-channel publishing – Same content, multiple destinations (web, mobile, IoT)
  • Scalable infrastructure – Built on Java for enterprise-grade performance

3. Official Clients (SDKs)

Integrate Nodify with your tech stack using official clients. Each client supports full API functionality including content retrieval, click tracking, feedback submission, and duplex communication where applicable.

Language Repository Features
Java / Kotlin nodify-clients/java Full API, duplex support, JVM native
Python nodify-clients/python Full API, async support, duplex
Node.js nodify-clients/nodejs Full API, WebSocket duplex, npm package
PHP nodify-php-client Full API, Composer ready, duplex

Quick Start Examples

Node.js:

const Nodify = require('nodify-client');
const client = new Nodify({ apiKey: 'your_key' });

// Real-time duplex connection
client.connectDuplex();
client.on('contentUpdate', (data) => console.log(data));

Python:

from nodify import NodifyClient
client = NodifyClient(api_key='your_key')

# Async duplex
await client.subscribe('content-updates', callback=my_handler)

Java/Kotlin:

val client = NodifyClient("your_api_key")
client.duplex.subscribe { update ->
    println("Received: $update")
}

PHP:

use Nodify\NodifyClient;
$client = new NodifyClient('your_api_key');
$client->duplex()->on('update', function($data) {
    echo "Update: " . json_encode($data);
});

4. Structure and Content Creation

Content in Nodify is organized into nodes. Nodes can contain text, HTML, JSON, images, files, or any other format, and can be organized hierarchically. Each node supports i18n through language-specific fields.

Creating a Node

POST /v0/nodes
Content-Type: application/json
{
  "name": "blog",
  "language": "en"
}

Adding Content to a Node

POST /v0/contents
Content-Type: application/json
{
  "nodeCode": "{your_node_code}",
  "type": "text",
  "name": "article-1",
  "content": "<h1>Welcome to my first article</h1>",
  "slug": "welcome-to-my-first-article"
}

Content types supported: text, html, json, css, js, image, file

5. Data Management API

Store and retrieve structured data (key-value pairs) for configuration or application state.

POST /v0/datas
Content-Type: application/json
{
  "key": "user_settings",
  "value": { "theme": "dark", "notifications": true }
}
GET /v0/datas/key/{key}

6. Retrieving Content

Access your content via the REST API. You can retrieve either the full envelope (including metadata) or just the raw payload.

Full envelope (default):

GET /v0/content/code/{your_content_code}

Response includes: metadata, timestamps, language, version, and content.

Raw content only:

GET /v0/content/code/{your_content_code}?payloadOnly=true

Returns: Only the content body (useful for direct embedding).

Retrieve content by slug (SEO-friendly URL):

GET /v0/content/slug/{your_slug}

7. Tracking Clicks and Views

Nodify automatically tracks content displays. You can also manually increment click counters via the API.

Record a click:

PATCH /v0/content-clicks/contentCode/{your_content_code}

Get display statistics:

GET /v0/content-displays/charts

Get click statistics:

GET /v0/content-clicks/charts

8. User Feedback

Collect ratings and comments from your users.

POST /v0/feedbacks
Content-Type: application/json
{
  "contentCode": "article_123",
  "author": "john.doe@email.com",
  "rating": 5,
  "comment": "Great article!"
}

Retrieve feedback for content:

GET /v0/feedbacks/contentCode/{content_code}

9. Plugins

Nodify supports a plugin system for extending functionality. Use the $with() directive to load plugins.

$with(jquery3.7.1)
<p>This content uses the jQuery plugin.</p>

Built-in plugin examples:

  • jquery3.7.1 - jQuery library
  • markdown - Markdown parser
  • syntax-highlighter - Code highlighting

10. Templates

Templates allow you to build dynamic pages by combining independent content nodes. This is the core of Nodify's templating system.

Creating Templates

Example structure:

Content Type Unique Code Format
Header (global template) html-1 HTML
Footer html-2 HTML
CSS styles css-1 CSS
Body content html-3 HTML
JavaScript js-1 JS

Assembling the page:

<html>
<head>
    <style>$content(css-1)</style>
</head>
<body>
    $content(html-1) <!-- Header -->
    $content(html-3) <!-- Body -->
    $content(html-2) <!-- Footer -->
    <script>$content(js-1)</script>
</body>
</html>

Nesting Templates:

<header>
    <h1>$content(site-title)</h1>
    <nav>$content(category-list)</nav>
</header>

Multilingual Templates (i18n):

<!-- English version -->
$content(en-site-title)

<!-- French version -->
$content(fr-site-title)

Template Advantages:

  • Reusability – Components can be reused across multiple pages
  • Maintainability – Update once, reflect everywhere
  • Flexibility – Dynamically change content without modifying the main template
  • Modularity – Clean separation of concerns
  • i18n ready – Serve different language versions seamlessly

11. Authentication

Nodify provides flexible authentication options to suit different deployment scenarios. By default, a built-in authentication system is available and ready to use out of the box. For enterprise-grade security and single sign-on (SSO) scenarios, Nodify also supports OpenID Connect and OAuth 2.0.

Default Authentication

The default authentication system uses API keys that can be generated and managed directly from the Nodify admin dashboard.

Authorization: Bearer your_api_key

OpenID Connect (OIDC)

Nodify supports OpenID Connect, allowing you to integrate with identity providers such as:

  • Google
  • Microsoft Azure AD
  • Keycloak
  • Auth0
  • Any OpenID Connect compliant provider

Configuration example:

auth:
  type: openid
  provider: google
  clientId: your_client_id
  clientSecret: your_client_secret
  redirectUri: https://yourdomain.com/auth/callback

OAuth 2.0

For machine-to-machine communication or delegated access, Nodify fully supports OAuth 2.0 flows:

  • Client Credentials – For server-to-server API access
  • Authorization Code – For web applications
  • Implicit Flow – For single-page applications (SPAs)

OAuth 2.0 example:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret

📚 Detailed Documentation

For complete authentication configuration, including step-by-step setup guides for each provider, please refer to the dedicated Authentication section in the full Nodify documentation.

API Reference Summary

Method Endpoint Description
POST /v0/nodes Create a new node
POST /v0/contents Add content to a node
POST /v0/datas Store key-value data
GET /v0/content/code/{code} Retrieve content by code
GET /v0/content/slug/{slug} Retrieve content by slug (SEO)
PATCH /v0/content-clicks/contentCode/{code} Record a click
POST /v0/feedbacks Submit user feedback
GET /v0/content-displays/charts Get display analytics

Error Handling

Status Code Description
200 Success
201 Created
400 Bad Request – Invalid input
401 Unauthorized – Invalid or missing authentication
403 Forbidden – Insufficient permissions
404 Not Found – Resource does not exist
500 Internal Server Error

Conclusion

Nodify Headless CMS is the ideal choice for developers seeking an open source, Java-based solution with CaaS (Content as a Service) compatibility, duplex communication, official clients for PHP, Java/Kotlin, Python, and Node.js, a powerful REST API, i18n support, flexible templating, built-in analytics, and enterprise-ready authentication (OpenID, OAuth 2.0, or default). Whether you're building a blog, e-commerce site, mobile app backend, or enterprise platform, Nodify gives you the tools to manage content your way.

#Nodify #HeadlessCMS #OpenSource #Java #API #RESTAPI #CaaS #ContentAsAService #Duplex #RealTime #i18n #Authentication #OpenID #OAuth2 #SSO #DeveloperTools #APIDriven #WebDevelopment #DynamicPages #WebDesign #Templates #ContentManagement #FrontendDevelopment #BackendDevelopment #Coding #SoftwareDevelopment #TechStack #Docker #SEO #ContentTracking #UserFeedback #Plugins #PHP #Python #Nodejs #Kotlin

Clone this wiki locally