CETAN Documentation

This documentation covers the CETAN Web Application Server, logging, TLS, authentication, IP filtering, Safe secrets, Safe utilities, development environment setup, and building C++ REST web services using the CETAN REST API.

Develop Web Applications Using the CETAN REST API

The CETAN REST API enables developers to build high‑performance C++ web applications that run natively on the CETAN Web Application Server. It provides an object‑oriented framework for defining services, routing HTTP requests, generating responses, and integrating with CETAN’s logging, security, and configuration systems.

This section explains how to set up a complete development environment, then walks through building a fully functional REST application named rest-api-101 that exposes a simple “Hello, World!” endpoint.

Development Environment Setup

CETAN REST development typically uses a Linux server as the build host and a Windows workstation for editing source code. The example environment below uses Ubuntu 24.04.2 LTS with g++ (C++23) and Apache NetBeans on Windows with remote development.

Requirements

Linux server with GLIBC++ ≥ 3.4 and a C++23‑capable g++ compiler.
Windows workstation for development.
Apache NetBeans with the C/C++ plugin installed.
CETAN REST SDK installed on the Linux server.
Samba or NFS for shared project files.

Directory Layout

A typical project structure:

project/
  include/
  src/
  build/
  CMakeLists.txt
  cetan-rest-sdk/

Configure Samba Share on Linux

Create a shared directory such as /opt/dev.
Set appropriate ownership and permissions.
Add a [dev] share to /etc/samba/smb.conf.
Restart Samba and map the share as a drive (e.g., V:) on Windows.

Install and Configure Apache NetBeans

Extract a JDK (e.g., D:\dev\jdk-25.0.1).
Extract Apache NetBeans (e.g., D:\dev\netbeans).
Set netbeans_jdkhome in netbeans.conf.
Add the NetBeans distribution update center.
Install the C/C++ plugin.

If NetBeans reports an unpack200 error, copy the unpack200 binary from an older JDK into the new JDK’s bin directory.

Configure Remote Build Host

Add your Linux server as a C/C++ build host via SSH.
Use Samba/NFS for shared project files.
Map Windows V: to Linux /opt/dev.

Validate the Environment

Create a new C/C++ project on V:\.
Select the Linux build host and GNU toolchain.
Build and run a simple “Hello, world!” program.

Linking Against CETAN REST

Include the CETAN REST headers:

#include "Rest.h"
 #include "WebService.h"
 #include "Resource.h"

Ensure your runtime search path includes:

$ORIGIN/../lib

Develop the `cetan-rest-101` Web Application

This tutorial walks through creating a minimal REST application that exposes a single endpoint: /greeting/hello-world. The application returns a simple HTML “Hello, World!” page.

Create the `Greeting` WebService

// Greeting.h
 #ifndef GREETING_H
 #define GREETING_H

 #include "Response.h"
 #include "WebService.h"
 #include <vector>

 using namespace std;
 using namespace ctn;

 class Greeting : public WebService {
 public:
    Greeting();
    Response hello_world() noexcept;
    Response say_hello(Param name) noexcept;
    virtual ~Greeting();
 private:
    vector<Resource*> register_resources() const override final;
 };

 #endif /* GREETING_H */

// Greeting.cpp
#include "Greeting.h"

Greeting::Greeting() : WebService("/greeting") {}

Response Greeting::hello_world() noexcept {
    Response resp(200);
    resp.body("<html><head><title>Hello World from CETAN REST</title></head>"
              "<body><center><font size=\\"25\\">Hello, World!</font>"
              "</center></body></html>");
    return resp;
}

Response Greeting::say_hello(Param name) noexcept {
   try {
      Response resp(200);
      string msg = "<html><head><title>Hello from CETAN REST</title></head><body><center><font size=\"25\">Hello, ";
      msg.append(name.value()).append("!</font></center></body></html>");
      resp.body(msg);   
      return resp;      
   }
   catch(...) {
      return Response(500);
   }
}

vector<Resource*> Greeting::register_resources() const {
    vector<Resource*> resources;
    resources.emplace_back(new Resource("GET", "/hello-world", &Greeting::hello_world));
    resources.emplace_back(new Resource("GET", "/say-hello/{name}", &Greeting::say_hello, Param("name")));
    return resources;
}

Greeting::~Greeting() {}

The full path for these endpoints become:
/greeting/hello-world under the application’s root URL.
/greeting/say-hello/{name} under the application’s root URL.

Create the `RestAPI101` Application Class

// RestAPI101.h
#ifndef RESTAPI101_H
#define RESTAPI101_H

#include "REST.h"
#include "WebService.h"
#include <set>

using namespace std;
using namespace ctn;
class RestAPI101 : public REST {
public:
    RestAPI101();
    virtual ~RestAPI101();
private:
    REST* create_cetan_app() const override final;
    set<WebService*> register_services() const override final;
};

#endif /* RESTAPI101_H */

// RestAPI101.cpp
#include "REST.h"
#include "Greeting.h"
#include "RestAPI101.h"
RestAPI101::RestAPI101() {}

REST* RestAPI101::create_cetan_app() const {
    return new RestAPI101();
}

set<WebService*> RestAPI101::register_services() const {
    set<WebService*> services;
    services.emplace(new Greeting());
    return services;
}

RestAPI101::~RestAPI101() {}

Build Configuration

Compile with -std=c++23.
Output file: cetan-rest-101.ctn.
Add lib to library directories.
Set runtime search path to $ORIGIN/../lib.
Link against libctn-rest.so.

Deploy to CETAN

Copy cetan-rest-101.ctn into the server’s lib directory.
Add an application entry to cetan_config.xml:

<applications>
  <app name="cetan-rest-101">
    <root_url>/rest-101</root_url>
    <app_file>cetan-rest-101.ctn</app_file>
  </app>
</applications>

After restarting the CETAN Web Application Server, the endpoints become:

https://your-server.com/rest-101/greeting/hello-world

https://your-server.com/rest-101/greeting/say-hello/{name}

Example: https://your-server.com/rest-101/greeting/say-hello/John

You should now see the “Hello, World!” or "Hello, John!" HTML page in your browser. This completes the rest-api-101 tutorial.