HTTP Handlers

This page summarizes how to properly use HTTP Handlers.

Please see Mandarine MVC Controllers before continuing.

How to properly use HTTP Handlers

HTTP handlers as we have mentioned before, are just methods that are decorated with route decoration. Although, they can handle complex operations by using HTTP Parameter decorators.

HTTP Parameter Decorators

They are decorators that are used in the parameters of a HTTP Handler. Every decorator provides a different functionality, but the objective is the same for all of them: The interaction of the current request & your mandarine-powered web application.

• @RouteParam(name?: string)

  • It will bring the value of the param declared on the route path. This value comes from the client's request.

  • name is used to identify what parameter from the route path we are trying to get

    • Optional

    • If name is ignored, then its value will be the parameter's key.

• @QueryParam(name?: string)

  • It will bring the value of the desired query parameter. This value comes from the URL a client has requested.

  • name is used to identify what query parameter from the request's url we are trying to get

    • Optional

    • If name is ignored, then its value will be the parameter's key.

• @RequestBody()

  • It will bring the value from request's body.

    • It is the equivalent to request.body().
    • Mandarine will try to parse it when the content type of the body is application/x-www-form-urlencoded or application/json . If the content-type is not known, the whole body object will be inject it instead.

• @Session()

  • It will bring the current session object located in the request.

• @Cookie(name?: string)

  • It will bring the cookie with the key name

  • name is used to identify what cookie from the request we are trying to get

    • Optional

    • If name is ignored, then its value will be the parameter's key.

• @ServerRequestParam()

  • It will bring the all the information available from the request made by a client.

    • The result is a ServerRequest object

• @RequestParam()

  • It will bring the all the information available from the request made by a client.

    • The result is a Request object from Oak.

• @ResponseParam()

  • It will bring the value from the current response given by the server before being delivered to the client.

  • Modifications to the request can and will affect the outcome of the response delivered to the client after the HTTP handler has been executed.

• @Model()

  • It will inject the ViewModel object, used to create data models for templates. (More information here)

Usage

@RouteParam

import { Controller, GET, RouteParam, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

@Controller('/api')
export class Foo {
     
    @GET('/say-hi/:personsName')
    public httpHandler1(@RouteParam() personsName: string): string {
        return `Hello ${personsName}, welcome to Mandarine.TS`;
    }
    
    // This one specifies manually what parameter we are trying to get
    @GET('/say-hello/:name')
    public httpHandler2(@RouteParam('name') personsName: string): string {
        return `Hello ${personsName}, welcome to Mandarine.TS`;
    }

}

new MandarineCore().MVC().run();

Request

# http://localhost:8080/api/say-hi/Bill
Hello Bill, Welcome to Mandarine.TS

# http://localhost:8080/api/say-hello/Mark
Hello Mark, Welcome to Mandarine.TS

@QueryParam

import { Controller, GET, QueryParam, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

@Controller('/api')
export class Foo {
     
    @GET('/say-hi')
    public httpHandler1(@QueryParam() personsName: string): string {
        return `Hello ${personsName}, welcome to Mandarine.TS`;
    }
    
    // This one specifies manually what query parameter we are trying to get
    @GET('/say-hello')
    public httpHandler2(@QueryParam('name') personsName: string): string {
        return `Hello ${personsName}, welcome to Mandarine.TS`;
    }

}

new MandarineCore().MVC().run();

Result

# http://localhost:8080/say-hi?personsName=Will
Hello Will, welcome to Mandarine.TS

# http://localhost:8080/say-hello?name=Cristopher
Hello Cristopher, welcome to Mandarine.TS

@RequestBody

import { Controller, POST, QueryParam, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

interface UserData {
    id: number;
    username: string;
}

@Controller('/api')
export class Foo {
    
    @POST('/add-user-json')
    public handler(@RequestBody() data: UserData) {
        return `User with Id ${data.id} and Username ${data.username} has been added`;
    }
    
    @POST('/add-user-form-url-encoded')
    public handler(@RequestBody() data: UserData) {
        return `User with Id ${data['id']} and Username ${data['username']} has been added`;
    }
    
}

new MandarineCore().MVC().run();

Result

# POST /add-user-json HTTP/1.1
# Host: 127.0.0.1:8080
# Content-Type: application/json
# {
	"name": "Andres",
	"id": 1
}

User with Id 1 and Username Andres has been added

# POST /add-user-form-url-encoded HTTP/1.1
# Host: 127.0.0.1:8080
# Content-Type: application/x-www-form-urlencoded
# name=Leonard&id=2

User with Id 2 and Username Leonard has been added

@Session

import { Controller, GET, Session, MandarineCore } from "https://deno.land/x/mandarinets/mod.ts";

@Controller()
export class Foo {

    @GET('/session-counter')
    public helloWorld(@Session() session: any): string {
        if(session.times == undefined) session.times = 0;
        else session.times = session.times + 1;

        return `Times = ${session.times}`;
    }

}

new MandarineCore().MVC().run();

Result

# http://localhost:8080/session-counter
Times 0

# http://localhost:8080/session-counter
Times 1

# http://localhost:8080/session-counter
Times 2

.......