Creating RESTful APIs¶

In this chapter, we explain how iFun Engine helps game server integrate into monitoring/management infrastructure.

To work with external systems, a game server should be able to expose its internal states and update the states according to incoming commands. RESTful API seems like a perfect solution to meet the requirement. iFun Engine provides an efficient way to add RESTful APIs to a game server.

On iFun Engine, RESTful APIs can be added simply by declaring API URLs (in Perl-style regular expression patterns) and matching API handler functions. Once an API request arrives, iFun Engine routes the request and passes it to a registered handler.

API Handler¶

Registering a handler

You first need to register a handler function for an API URL using ApiService::RegisterHandler.

ApiService::RegisterHandler(HTTP method, URL pattern, Handler function)

HTTP method: http::kGet, http::kPut, http::kPost, http::kDelete, http::kHead.
URL pattern: in the Perl’s regular expression pattern. Hence, Perl’s named group like (?<NAME>pattern) can be used. Matched groups will be passed to a handler in the form of string dictionary. (See the example below.)
Handler function : functor to process the URL pattern.

Writing a handler

Handler function should be in the form below. In its body, it should fill the passed response.

void MyHandler(Ptr<http::Response> response,
               const http::Request &request,
               const ApiService::MatchResult &params) {
  response->status_code = http::kOk; // response status code
  response->body = ... // response body
}

Example

Below, we added a simple API URL /v1/example/hello/ and its variation /v1/example/hello2/ to take parameters in a URL pattern.

// ...

// Registers API handlers upon bootstrapping.
ApiService::RegisterHandler(
    http::kGet, boost::regex("/v1/example/hello"), OnHello);
ApiService::RegisterHandler(http::kGet,
    boost::regex("/v1/example/hello2/(?<name>\\w+)/(?<age>\\w+)/"), OnHello2);

// ...

// request: http://localhost:8014/v1/example/hello
// response: hello!
void OnHello(Ptr<http::Response> response,
    const http::Request &request,
    const ApiService::MatchResult &params) {
  response->status_code = http::kOk;
  response->header.insert(std::make_pair("Content-Type", "text/plain"));
  response->body = "hello!";
}


// request: http://localhost:8014/v1/example/hello2/bob/24
// response:
// {
//   "name": "bob",
//   "age": "24"
// }
void OnHello2(Ptr<http::Response> response,
    const http::Request &request,
    const ApiService::MatchResult &params) {
  Json msg;
  msg["name"] = params["name"];
  msg["age"] = params["age"];
  response->status_code = http::kOk;
  response->header.insert(std::make_pair("Content-Type", "application/json"));
  response->body = msg.ToString();
}

MANIFEST.json Configuration¶

To use the RESTful API feature, MANIFEST.json should have a component named “ApiService” and configuring arguments.

{
  "ApiService": {
    // Port to listen. Defaults to 8014. Set to 0 to disable ApiService.
    "api_service_port" : 8014
  }
}

Please note that iFun Engine’s RESTful API does not provide an access control, for it is assumed to be used internally for a management purpose. Hence, OS-level access control such as Linux’s iptables is required.