# High Level Overview

This is the high level overview of Oat++ API.

# API Controller - Request Mapping

For more info see Api Controller

# Declare Endpoint

ENDPOINT("PUT", "/users/{userId}", putUser,
         PATH(Int64, userId),
         BODY_DTO(Object<UserDto>, userDto)) 
{
  userDto->id = userId;
  return createDtoResponse(Status::CODE_200, m_database->updateUser(userDto));
}

# Add CORS for Endpoint

For more info see Api Controller / CORS

ADD_CORS(putUser)
ENDPOINT("PUT", "/users/{userId}", putUser,
         PATH(Int64, userId),
         BODY_DTO(Object<UserDto>, userDto)) 
{
  userDto->id = userId;
  return createDtoResponse(Status::CODE_200, m_database->updateUser(userDto));
}

# Endpoint with Authorization

For more info see Api Controller / Authorization

using namespace oatpp::web::server::handler;
  
ENDPOINT("PUT", "/users/{userId}", putUser,
         AUTHORIZATION(std::shared_ptr<DefaultBasicAuthorizationObject>, authObject),
         PATH(Int64, userId),
         BODY_DTO(Object<UserDto>, userDto)) 
{
  OATPP_ASSERT_HTTP(authObject->userId == "Ivan" && authObject->password == "admin", Status::CODE_401, "Unauthorized");
  userDto->id = userId;
  return createDtoResponse(Status::CODE_200, m_database->updateUser(userDto));
}

# API Client - Retrofit / Feign Like Client

For more info see Api Client

# Declare Client

class UserService : public oatpp::web::client::ApiClient {
public:

  API_CLIENT_INIT(UserService)

  API_CALL("GET", "/users", getUsers)
  API_CALL("GET", "/users/{userId}", getUserById, PATH(Int64, userId))

};

# Using API Client

auto response = userService->getUserById(id);
auto user = response->readBodyToDto<oatpp::Object<UserDto>>(objectMapper);

# Object Mapping

For more info see Data Transfer Object (DTO).

# Declare DTO

class UserDto : public oatpp::Object {

  DTO_INIT(UserDto, Object)

  DTO_FIELD(Int64, id);
  DTO_FIELD(String, name);

};

# Serialize DTO Using ObjectMapper

using namespace oatpp::parser::json::mapping;

/* Create JSON object mapper */
ObjectMapper objectMapper;

auto user = UserDto::createShared();
user->id = 1;
user->name = "Ivan";

/* Serialize DTO to JSON */
auto json = objectMapper.writeToString(user);

Output:

{
  "id": 1,
  "name": "Ivan"
}

# Swagger-UI Annotations

For more info see Endpoint Annotation And API Documentation

# Additional Endpoint Info

ENDPOINT_INFO(putUser) {
  // general
  info->summary = "Update User by userId";
  info->addConsumes<Object<UserDto>>("application/json");
  info->addResponse<Object<UserDto>>(Status::CODE_200, "application/json");
  info->addResponse<String>(Status::CODE_404, "text/plain");
  // params specific
  info->pathParams["userId"].description = "User Identifier";
}
ENDPOINT("PUT", "/users/{userId}", putUser,
         PATH(Int64, userId),
         BODY_DTO(Object<UserDto>, userDto)) 
{
  userDto->id = userId;
  return createDtoResponse(Status::CODE_200, m_database->updateUser(userDto));
}

# ORM Framework

For more info see Oat++ ORM Framework

# Declare DbClient

class MyClient : public oatpp::orm::DbClient {
public:

  MyClient(const std::shared_ptr<oatpp::orm::Executor>& executor)
    : oatpp::orm::DbClient(executor)
  {}

  QUERY(createUser,
        "INSERT INTO users (username, email, role) VALUES (:username, :email, :role);",
        PARAM(oatpp::String, username), 
        PARAM(oatpp::String, email), 
        PARAM(oatpp::Enum<UserRoles>::AsString, role)) 

  QUERY(getUserByName, 
        "SELECT * FROM users WHERE username=:username;", 
        PARAM(oatpp::String, username)) 
        
};

# DbClient Usage Example

...

/* Create MyClient database client */
MyClient client(executor);

/* Create new user in the database */
client.createUser("admin", "admin@domain.com", UserRoles::ADMIN);

/* Find user by username in the database */
auto result = client.getUserByUsername("admin");

/* Retrieve query result as a vector of UserDto objects */
/* Of cause, UserDto had to be previously defined */
auto dataset = result->fetch<oatpp::Vector<oatpp::Object<UserDto>>>();

/* And we can easily serialize result as a json string using json object mapper */
auto json = jsonObjectMapper.writeToString(dataset);

/* Print the resultant json */
std::cout << json->c_str() << std::endl;

Output:

[
  {
    "name": "admin",
    "email": "admin@domain.com",
    "role": "ROLE_ADMIN"
  }
]

# Modules And Build Status

To get an overview of oatpp modules, their hierarchy, and build status - see build status.