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 ¶ms) {
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 ¶ms) {
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 ¶ms) {
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.