CETAN Documentation

CETAN C++ API (SDK)

The CETAN SDK provides a set of C++ classes for building RESTful services, handling requests, generating responses, managing uploads, and defining routes. This section documents each class in the REST framework.

REST Application Base Class

The REST class is the foundation of every CETAN REST application. It manages application initialization, service registration, and endpoint discovery. Developers derive from this class to define their application and register WebService components.

Constructors & Lifecycle

  REST();
  virtual ~REST();

The constructor initializes the REST application. The destructor cleans up registered services and internal state.

Members

const string tag = "REST";

A default tag used for logging or identification.

Endpoint Discovery

  const string& json_endpoints() const;
  const vector<string>& app_endpoints() const;

• json_endpoints() — returns all registered endpoints in JSON format.
• app_endpoints() — returns a list of endpoint paths for the application.

Initialization Hook

protected:
  virtual void init();

Override init() in your derived class to configure services, routes, and application‑specific initialization logic.

Service Registration (Required)

private:
  virtual set<WebService*> register_services() const = 0;

Every REST application must implement register_services() to return the set of WebService instances that belong to the application. Each service defines its own routes and handlers.

WebService Base Class

WebService represents a REST resource bound to a specific base path. Developers derive from this class to implement REST endpoints using Resource objects. Each service is responsible for registering its own routes.

Constructors & Semantics

  WebService(const string& path);
  WebService(WebService&& orig);
  WebService& operator=(WebService&& orig);

  WebService(const WebService& orig) = delete;
  WebService& operator=(const WebService& orig) = delete;

  virtual ~WebService();

A WebService is move‑only. The path parameter defines the base URL under which all service endpoints are registered.

Accessors

  Request get_request() const;
  const string& app_name() const;
  const string& app_root_url() const;
  const string& document_root() const;

  const REST* get_app() const;
  const string& get_path() const;
  const vector<string>& get_endpoints() const;

• get_request() — returns the current request object.
• app_name() — name of the owning REST application.
• app_root_url() — root URL of the application.
• document_root() — static file root directory.
• get_app() — pointer to the owning REST instance.
• get_path() — base path for this service.
• get_endpoints() — list of registered endpoint paths.

Resource Registration (Required)

private:
  virtual vector<Resource*> register_resources() const = 0;

Derived classes must implement register_resources() to return the list of Resource objects that define the service’s HTTP endpoints.

Response Class

Response represents an HTTP response, including status code, headers, cookies, and body content.

Header Enumeration

enum Header {
  Cache_Control, Connection, Date, Pragma, Trailer, Transfer_Encoding, Upgrade, Via, Warning,
  Accept, Accept_Charset, Accept_Encoding, Accept_Language, Authorization, Expect, From, Host,
  If_Match, If_Modified_Since, If_None_Match, If_Range, If_Unmodified_Since, Max_Forwards,
  Proxy_Authorization, Range, Referer, TE, User_Agent, Accept_Ranges, Age, ETag, Location,
  Proxy_Authenticate, Retry_After, Server, Vary, WWW_Authenticate, Allow, Content_Encoding,
  Content_Language, Content_Length, Content_Location, Content_MD5, Content_Range, Content_Type,
  Expires, Last_Modified, Cookie, Set_Cookie
};

Constructors

  Response();
  Response(int code);
  Response(Response&& orig);
  Response& operator=(Response&& orig);

  Response(const Response& orig) = delete;
  Response& operator=(const Response& orig) = delete;

  virtual ~Response();

Status & Body

  bool has_content() const;
  Response& status(int code);
  int status() const;

  void body(const string_view& body);
  void body(const char* buf, unsigned size);
  const string& body() const;

Headers & Cookies

  string_view header() const;
  Response& header(const char* buf, unsigned size);
  Response& header(const map<string,string>& header);
  Response& header(Header header, const string& value);
  Response& header(const string& name, const string& value);
  Response& header(const string_view& n, const string_view& v);
  Response& header(const map<string_view,string_view>& headers);

  Response& set_cookie(const string& name, const string& value);

ResourceBuilder Class

ResourceBuilder registers HTTP routes and binds them to member function handlers.

Route Registration

  template<typename MemPtr>
  auto PUT(const string& path, MemPtr mptr);

  template<typename MemPtr>
  auto POST(const string& path, MemPtr mptr);

  template<typename MemPtr>
  auto DEL(const string& path, MemPtr mptr);

  template<typename MemPtr>
  auto GET(const string& path, MemPtr mptr);

  template<typename MemPtr>
  auto add(const string& method, const string& path, MemPtr mptr);

Each method returns a RouteBuilder for additional configuration.

Request Class

Request represents an incoming HTTP request, including headers, method, URI, cookies, parameters, and uploaded files.

Constructors

  Request(void*);
  Request(Request&& orig);
  Request& operator=(Request&& orig);
  Request(const Request& orig);
  Request& operator=(const Request& orig);

  virtual ~Request();

General Properties

  Header header() const;
  bool keepalive() const;
  bool has_content() const;
  bool authenticated() const;

  string_view method() const;
  string_view get_uri() const;
  string_view get_path() const;
  string_view request_line() const;

Content & Types

  string_view mime_type() const;
  string_view accept_type() const;
  string_view content_type() const;
  unsigned long content_length() const;

Query & Parameters

  string_view get_query_string() const;
  unordered_map<string_view,string_view> get_params() const;
  string_view get_param(const string& name) const;

Headers & Cookies

  string_view get_header(const string& name) const;
  list<string_view> get_cookies() const;
  string_view get_cookie(const string& name) const;

Uploads

list<FileUpload> get_upload_files() const;

Param Class Template

Param represents a named parameter with an optional value.

Constructors

  Param();
  Param(string&& name);
  Param(const char* name);
  Param(const string& name);
  Param(const string_view& name);

  Param(Param&& orig);
  Param(const Param& orig);
  Param& operator=(Param&& orig);
  Param& operator=(const Param& orig);

Name & Value

  void name(string&& s);
  void name(const char* s);
  void name(const string& s);
  void name(const string_view& s);

  string param() const;
  bool has_value() const;
  const string& name();
  char value() const;

Header Class

Header provides access to HTTP header fields and cookies.

Constructors

  Header();
  Header(Header&& orig);
  Header(const Header& orig);
  Header& operator=(Header&& orig);
  Header& operator=(const Header& orig);

  virtual ~Header();

Accessors

  string_view view() const;
  const header_t& get() const;

  list<string_view> get_cookies() const;
  string_view get(const string& name) const;
  string_view get_cookie(const string& name) const;

FileUpload Class

FileUpload represents a single uploaded file in a multipart request.

Constructors

  FileUpload();
  FileUpload(const string& filename);
  FileUpload(HTTPFile* file);
  FileUpload(FileUpload&& orig);
  FileUpload(const FileUpload& orig);
  FileUpload& operator=(FileUpload&& orig);
  FileUpload& operator=(const FileUpload& orig);

  virtual ~FileUpload();

Properties & Operations

  bool has_content() const;
  ssize_t file_size() const;
  string_view filename() const;
  string_view content_type() const;
  const string& name_id();

  int move_file(const WebService*, const string& new_dir) const;
  int save_as(const WebService*, const string& dir, const string& name);

Stream Class

Stream represents an in‑memory content buffer.

Constructors

  Stream();
  Stream(Stream&& orig);
  Stream(const Stream& orig);
  Stream& operator=(Stream&& orig);
  Stream& operator=(const Stream& orig);

  virtual ~Stream();

Accessors

  unsigned int length() const;
  const string_view& view() const;
  const string_view& content_type() const;
  ssize_t save_as(const string& filename) const;

Uri Class

Uri stores a parsed URI string for a request or resource.

Constructors

  Uri();
  Uri(Uri&& orig);
  Uri(const Uri& orig);
  Uri& operator=(Uri&& orig);
  Uri& operator=(const Uri& orig);

  virtual ~Uri();

Accessor

const string_view& get() const;

QueryString Class

QueryString stores the raw query component of a URI.

Constructors

  QueryString();
  QueryString(QueryString&& orig);
  QueryString(const QueryString& orig);
  QueryString& operator=(QueryString&& orig);
  QueryString& operator=(const QueryString& orig);
  virtual ~QueryString();

Accessors

string_view get()

AuthenticatedUser Class

AuthenticatedUser represents the identity of the authenticated client associated with a request.

Constructors

  AuthenticatedUser();
  AuthenticatedUser(const void* identity);
  AuthenticatedUser(AuthenticatedUser&& orig);
  AuthenticatedUser(const AuthenticatedUser& orig);
  AuthenticatedUser& operator=(AuthenticatedUser&& orig);
  AuthenticatedUser& operator=(const AuthenticatedUser& orig);    
  virtual ~AuthenticatedUser();

Accessors

  string_view get_id() const;
  string_view get_groups() const;
  string_view get_display() const;
  string_view get_provider() const;

RouteBuilder Class

The RouteBuilder class is a lightweight helper used internally by ResourceBuilder to construct Resource objects. It binds an HTTP method, a path, and a member function pointer, and then produces a fully constructed Resource instance when build() is invoked.

Constructor

RouteBuilder(string method, string path, MemPtr ptr)
  : method(method), path(path), memptr(ptr) {}

Creates a route builder for the given HTTP method, URL path, and handler member function pointer memptr.

Build Functions

  template<typename... Args>
  Resource* build(Args&&... args) {
    return new Resource(method, path, memptr, forward<Args>(args)...);
  }

  template<typename... Args>
  Resource* build(const Args&... args) {
    return new Resource(method, path, memptr, args...);
  }

• build(Args&&...) — forwards constructor arguments perfectly to the Resource constructor.
• build(const Args&...) — passes arguments by const reference.

Both overloads return a dynamically allocated Resource object configured with the method, path, and handler pointer captured by the RouteBuilder.

Resource Parameter Types

The REST framework supports a set of parameter types that may be used as arguments to resource handler member functions. These types allow handlers to access request metadata, headers, cookies, query strings, uploaded files, and typed parameters extracted from the URI.

Supported Parameter Types

• Request — provides full access to the incoming HTTP request, including headers, cookies, method, URI, and uploaded files.
• Response — represents the HTTP response being constructed by the handler.
• Param<T> — a typed parameter extracted from the URI path or query string.
• Header — identifies a specific HTTP header to retrieve from the request.
• FileUpload — represents an uploaded file included in a multipart/form-data request.
• QueryString — provides access to the raw encoded query component of the request URI.
• AuthenticatedUser — represents the authenticated identity associated with the request, if any.
• Stream — provides access to the request body as a streaming input source, enabling incremental or large-payload processing.
• Uri — stores the parsed URI of the request, including path, query, and component accessors.

These parameter types may be combined in any order within a resource handler’s signature. The framework automatically resolves and injects each parameter based on the incoming request.