Single Liner Payload Read…
It’s time for another blog post on a cool feature as the Ballerina Swan Lake beta1 was released last week. This is a pretty short post to give you a heads-up on one of the new features of Ballerina HTTP package.
HTTP client plays a significant role in the system by connecting to different endpoint over the network. The client is quite rich in terms of its network functionalities such caching, resiliency, redirection, cookie, security,.. etc.
This post is about another aspect of the client, which is the response payload retrieval.
People invoke endpoints mostly to play with data/payload. So how do you retrieve it from a ballerina program? The answer would be, accessing is via the getXXXPayload() methods of the http:Response as follows. That’s correct!
In fact, this can be further shortened for a single liner by having the expected payload type (json) as the return type of get() operation. The client operation is able to infer the expected payload type from the LHS variable type which is a super cool feature which the language.
As shown above, you don’t need to specify it on the remote method itself as an argument unless the LHS variable type is var. In such cases, pass the typedesc to the targetType argument.
With this approach, you can simply access the payload as one of the following types:string, json, xml, byte[], record, record[].
One important fact is that, when the user expects the payload extraction to be happened, the erroneous HTTP responses (4XX and 5XX status code range) are returned as ballerina error of the client operation. So the micro-services focus on success payload can simple ignore the error. However, the 4XX responses are categorised under http:ClientRequestError and 5XX responses goes under http:RemoteServiceError. Still the payload, headers and status code are accessible in the error detail as follows;
If you return or do a checkon the error from a resource function, the error will be serialised as a proper response along with the headers, properties, and payload.
Last but not least, here comes the data binding. When the response payload type is JSON, you can simply convert a compatible payload into ballerina record or record[] by having it as return type as follows;
Hello Eve Hewson!
Joining from California
Internally the client extracts and binds the payload into the Person record. For a successful binding, the response payload should contain the fields of the record. In this sample, the endpoint is returning the following payload which is compatible with the record.
{
“name”: “Eve Hewson”,
“age”: 29,
“origin”: “Ireland”,
“address”: {
“number”: “9150 Wilshire Blvd.”,
“state”:”California”
}
}
In the case of a binding error, the client returns it as an http:PayloadBindingError .
Finally, I must say that, single line extraction does not affect the http:Response at any cost. Whenever user needs to dig into HTTP headers and response properties along with the payload, it can still be done by having http:Response as the expected type.
So it’s time to include this cool feature into your program! Happy coding!!!
Cheers!!
