import ballerina/http;

type Student record {
    string Name;
    int Grade;
    map<any> Marks;
};

service /hello on new http:Listener(9090) {

    // The `orderDetails` parameter in [Payload annotation](https://docs.central.ballerina.io/ballerina/http/latest/records/Payload)
    // represents the entity body of the inbound request.
    resource function post bindJson(@http:Payload json orderDetails)
            returns json|http:BadRequest {
        //Accesses the JSON field values.
        var details = orderDetails.Details;
        if (details is json) {
            return details;
        } else {
            http:BadRequest response = {body: "Order Details unavailable"};
            return response;
        }
    }

    //Binds the XML payload of the inbound request to the `store` variable.
    @http:ResourceConfig {
        consumes: ["application/xml"]
    }
    resource function post bindXML(@http:Payload xml store) returns xml {
        //Accesses the XML content.
        xml city = store.selectDescendants("{http://www.test.com}city");
        return city;
    }

    //Binds the JSON payload to a custom record. The payload's content should
    //match the record.
    @http:ResourceConfig {
        consumes: ["application/json"]
    }
    resource function post bindStruct(@http:Payload Student student)
            returns json {
        //Accesses the fields of the `Student` record.
        string name = <@untainted>student.Name;
        int grade = <@untainted>student.Grade;
        string english = <@untainted string>student.Marks["English"];
        return {Name: name, Grade: grade, English: english};
    }
}

Service Data Binding

HTTP service data binding helps to access the request payload through the last resource signature parameter. The parameter name should be declared in the resource config under the body annotation. string, json, xml, byte[], record, and record[] are supported as parameter types.

For more information on the underlying module, see the HTTP module.

import ballerina/http;
type Student record {
    string Name;
    int Grade;
    map<any> Marks;
};
service /hello on new http:Listener(9090) {
    resource function post bindJson(@http:Payload json orderDetails)
            returns json|http:BadRequest {

The orderDetails parameter in Payload annotation represents the entity body of the inbound request.

        var details = orderDetails.Details;
        if (details is json) {
            return details;
        } else {
            http:BadRequest response = {body: "Order Details unavailable"};
            return response;
        }
    }

Accesses the JSON field values.

    @http:ResourceConfig {
        consumes: ["application/xml"]
    }
    resource function post bindXML(@http:Payload xml store) returns xml {

Binds the XML payload of the inbound request to the store variable.

        xml city = store.selectDescendants("{http://www.test.com}city");
        return city;
    }

Accesses the XML content.

    @http:ResourceConfig {
        consumes: ["application/json"]
    }
    resource function post bindStruct(@http:Payload Student student)
            returns json {

Binds the JSON payload to a custom record. The payload’s content should match the record.

        string name = <@untainted>student.Name;
        int grade = <@untainted>student.Grade;
        string english = <@untainted string>student.Marks["English"];
        return {Name: name, Grade: grade, English: english};
    }
}

Accesses the fields of the Student record.

# To start the service, navigate to the directory that contains the
# `.bal` file and use the `bal run` command below.
bal run http_data_binding.bal
#Service deployment
[ballerina/http] started HTTP/WS listener 0.0.0.0:9090
# To invoke the `bindJson` resource, execute the below HTTP request.
curl -v http://localhost:9090/hello/bindJson -d '{ "Details": { "ID": "77999", "Name": "XYZ"} , "Location": { "No": "01", "City": "Colombo"}}' -H "Content-Type:application/json"
> POST /hello/bindJson HTTP/1.1
> Host: localhost:9090
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Type:application/json
> Content-Length: 92
>
* upload completely sent off: 92 out of 92 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 28
< server: ballerina
<
* Connection #0 to host localhost left intact
{"ID":"77999", "Name":"XYZ"}* Closing connection 0
# To invoke the `bindXML` resource, execute the below HTTP request.
curl -v http://localhost:9090/hello/bindXML -d "<h:Store id = \"AST\" xmlns:h=\"http://www.test.com\"><h:street>Main</h:street><h:city>94</h:city></h:Store>" -H "Content-Type:application/xml"
> POST /hello/bindXML HTTP/1.1
> Host: localhost:9090
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Type:application/xml
> Content-Length: 104
>
* upload completely sent off: 104 out of 104 bytes
< HTTP/1.1 200 OK
< content-type: application/xml
< content-length: 49
< server: ballerina
<
* Connection #0 to host localhost left intact
<h:city xmlns:h="http://www.test.com">94</h:city>* Closing connection 0
# To invoke the `bindStruct` resource, execute the below HTTP request.
curl -v http://localhost:9090/hello/bindStruct -d '{ "Name": "John", "Grade": 12, "Marks": {"English" : "85", "IT" : "100"}}' -H "Content-Type:application/json"
> POST /hello/bindStruct HTTP/1.1
> Host: localhost:9090
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Type:application/json
> Content-Length: 73
>
* upload completely sent off: 73 out of 73 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 43
< server: ballerina
<
* Connection #0 to host localhost left intact
{"Name":"John", "Grade":12, "English":"85"}* Closing connection 0