module restful_annot
import nitcorn::restful
+import nitcorn::pthreads
# An action root to its `restful` methods
class MyAction
super RestfulAction
- # Method answering requests like `foo?s=some_string&i=42&b=true`
+ # Method answering requests such as `foo?s=some_string&i=42&b=true`
#
# By default, the name of the HTTP resource is the name of the method.
# Responds to all HTTP methods, including GET, POST, PUT and DELETE.
+ #
+ # All arguments are deserialized from a JSON format,
+ # except for strings that are used as is.
fun foo(s: String, i: Int, b: Bool): HttpResponse
is restful do
var resp = new HttpResponse(200)
return resp
end
- # Method answering requests like `api_name?s=these_arguments_are_optional`
+ # Method answering requests such as `api_name?s=these_arguments_are_optional`
#
# This method is available as both `api_name` and `alt_name` in HTTP.
# Responds only to the GET and PUT HTTP method.
resp.body = "bar {s or else "null"} {i or else "null"} {b or else "null"}"
return resp
end
+
+ # Asynchronous method answering requests such as `async_service?str=some_string`
+ #
+ # This method is executed by the `thread_pool` attribute of this class.
+ # Be careful when using the `async` argument to follow all the good
+ # concurrent programming pratices.
+ fun async_service(str: String): HttpResponse
+ is restful(async) do
+
+ # "Work" for 2 seconds
+ 2.0.sleep
+
+ # Answer
+ var resp = new HttpResponse(200)
+ resp.body = "async_service {str}"
+ return resp
+ end
+
+ # Method with two complex parameters answering requests such as
+ # `complex_args?array=["a","b"]&data={"str":"asdf","more":{"str":"ASDF"}}`
+ #
+ # Collections and other classes can also be used as parameters,
+ # they will be deserialized from JSON format.
+ # By default, the JSON objects will be parsed as the type of the parameter.
+ # In the example above, the argument passed as `data` is deserialized as a `MyData`.
+ # However, you can use metadata in the JSON object to deserialize it
+ # as a subclass of `MyData`, as in this request where `data` is a `MyOtherData`:
+ #
+ # `complex_args?array=["a","b"]&data={"__class":"MyOtherData","str":"asdf","i":1234}`
+ #
+ # See the `json` package documentation for more information on JSON
+ # deserialization and the metadata values.
+ fun complex_args(array: Array[String], data: MyData): HttpResponse
+ is restful do
+ var resp = new HttpResponse(200)
+ resp.body = "complex_args {array} {data}"
+ return resp
+ end
+
+ # Catch all other request
+ redef fun answer(request, turi)
+ do
+ var resp = new HttpResponse(404)
+ resp.body = "Fallback answer"
+ return resp
+ end
+end
+
+# Simple data structure for `MyAction::complex_args`
+class MyData
+ serialize
+
+ # Some string
+ var str: String
+
+ # Some more data
+ var more: nullable MyData
+
+ redef fun to_s do return "<MyData str:{str} more:{more or else "null"}>"
+end
+
+# Another data structure, subclass to `MyData`
+class MyOtherData
+ super MyData
+ serialize
+
+ # An integer
+ var i: Int
+
+ redef fun to_s do return "<MyOtherData str:{str} more:{more or else "null"} i:{i}>"
end
var vh = new VirtualHost("localhost:8080")
# Set `rest_path` as the root for an instance of `MyAction`, so:
-# * `MyClass::foo` is available as `localhost:8080/rest_path/foo?...`,
-# * `MyClass::bar` is available as both `localhost:8080/rest_path/api_name?...`
+# * `MyClass::foo` is available as `localhost:8080/rest_path/foo?s=s&i=12&b=true`,
+# * `MyClass::bar` is available as both `localhost:8080/rest_path/api_name?s=s`
# and `localhost:8080/rest_path/alt_name?...`.
+# * `MyClass::async_service` is available as `localhost:8080/rest_path/async_service?str=str`
+# * `MyClass::complex_args` is available as
+# `localhost:8080/rest_path/complex_args?array=["a","b"]&data={"str":"asdf"}`
vh.routes.add new Route("rest_path", new MyAction)
var factory = new HttpFactory.and_libevent
# Arguments that are `nullable` are optional,
# if they are missing `null` is passed to the `restful` method.
#
-# The annotation accepts two kinds of arguments, in any order:
+# The annotation accepts three kinds of arguments, in any order:
#
# * String literals rename or add an alias for the HTTP resource.
# By default, the name of the HTTP resource is the name of the `restful` method.
# * Ids such as `GET`, `POST`, `PUT` and `DELETE` restrict which HTTP methods
# are accepted. By default, all HTTP methods are accepted.
#
+# * The `async` keyword triggers executing calls to this service asynchronously
+# by the `thread_pool` attribute of the `RestfulAction`.
+# By default, each call are executed on the same thread in a FIFO order.
+#
# See the example at `lib/nitcorn/examples/restful_annot.nit` or
# a real world use case at `contrib/benitlux/src/server/benitlux_controller.nit`.
#