REST service - Header parameter

The @http:header annotation allows reading header values from the request. The annotation can be used to annotate a given resource parameter. The name of the parameter must match the name of the header. If there is a mismatch, then the header name must be given in the annotation configuration. The resource parameter can be a simple type or an array type (i.e., string version or string[] versions). If there are many headers to read, a record type can be used as the parameter. Unless the parameter is optional (i.e., string? version), a 400 Bad Request response is sent to the client in the absence of the mapping header.

import ballerina/http;
import ballerina/mime;

type Album readonly & record {|
    string title;
    string artist;
|};

table<Album> key(title) albums = table [
    {title: "Blue Train", artist: "John Coltrane"},
    {title: "Jeru", artist: "Gerry Mulligan"}
];

service / on new http:Listener(9090) {

    // The `accept` argument with `@http:Header` annotation takes the value of the `Accept` request header.
    resource function get albums(@http:Header string accept) returns Album[]|http:NotAcceptable {
        if !string:equalsIgnoreCaseAscii(accept, mime:APPLICATION_JSON) {
            return http:NOT_ACCEPTABLE;
        }
        return albums.toArray();
    }
}

Run the service as follows.

$ bal run http_headers.bal

Invoke the service by executing the following cURL command in a new terminal.

$ curl "http://localhost:9090/albums" -H "Accept:application/json"[{"title":"Blue Train", "artist":"John Coltrane"}, {"title":"Jeru", "artist":"Gerry Mulligan"}]

Tip: You can invoke the above service via the client given in the HTTP client - Header parameter example.

Related links

• • http module - API documentation

• • HTTP service header parameter - Specification