Controller and REST - geronimo-iia/restexpress GitHub Wiki

• HTTP Methods, if not changed in the fluent (DSL) interface, map to the following:

  • GET --> read(Request, Response)
  • PUT --> update(Request, Response)
  • POST --> create(Request, Response)
  • DELETE --> delete(Request, Response)

• Request and Response parameter are optional.

• You can choose to return objects from the methods, if desired, which will be returned to the client in the body of the response.
  The object will be marshaled into JSON or XML, depending on the default or based on the format in the request (e.g. '.xml' or '?format=xml').

• If you choose to not return a value from the method (void methods) and using raw responses, then call response.setResponseNoContent() before returning to set the response HTTP status code to 204 (no content).
  Wrapped responses (JSEND style) are the default.
  So if you're using wrapped responses, there will always be a response returned to the client--therefore, you don't need to set the response.setResponseNoContent().
  Just return your objects--or not. RestExpress will handle things on your behalf!

• On successful creation, call response.setResponseCreated() to set the returning HTTP status code to 201.

• For more real-world examples, see the restexpress-sample directory which contains additional projects that setup RestExpress services.
  Simply do 'mvn clean install' to run them.
  Then to see what's available perform a GET on the route: '/routes/metadata' to get a list of all the routes(or endpoints) available (e.g. localhost:8000/routes/metadata in the browser).

Please see the echo application in examples/echo for a running example.

Example:

public class EchoController {
	private static final String ECHO_PARAMETER_NOT_FOUND = "'echo' header or query-string parameter not found. Please set query-string parameter 'echo' (e.g. ?echo=value).";
	private static final String ECHO_HEADER = "echo";

	public ChannelBuffer create(Request request, Response response) {
		response.setResponseCreated();
		return request.getEntity();
	}

	public String delete(Request request, Response response) {
		return request.getHeader(ECHO_HEADER, ECHO_PARAMETER_NOT_FOUND);
	}

	public String read(Request request, Response response) {
		String echo = request.getHeader(ECHO_HEADER);
		if (echo == null) {
			return "Please set query-string parameter 'echo' (e.g. ?echo=value)";
		}
		return echo;
	}

	public ChannelBuffer update(Request request, Response response) {
		return request.getEntity();
	}
}

If a controller instance is mapped with "/", we have:

• GET, http://localhost:8000/ --> read, if echo parameter is present in query string, return it
• PUT, http://localhost:8000/ --> update, return the request body
• POST, http://localhost:8000/ --> create, return an HTTP 204
• DELETE, http://localhost:8000/ --> delete, if echo parameter is present in query string, return it

If default mapping is used, if your controller did not implements a method, you will be warn by logger. But, in case of a specific mapping, a Configuration Exception will be raised for each defined method.