Redesign HTTP client APIs to expose HTTP errors as Ballerina errors

[sanjiva]

HttpClient always returns an HttpResponse currently (unless a low level network error happens).

That is the wrong design as it does not respect the Ballerina design goal of bringing networking aspects into the language. HTTP is a network protocol and an error in that is an error for the programmer.

4XX and 5XX status codes must give errors at the Ballerina level.

[chamil321]

Design notes document : https://docs.google.com/document/d/1ipV1aaO81I-1WoY9-ost0kK6vyFCcXbUcYoPbXFjWsw/edit?usp=sharing

[chamil321]

@sanjiva
This issue has been addressed along with HTTP Client data binding capability. The HTTP error responses which categorized under 4XX and 5XX status codes are no longer returned as http:Response typed value when the user specifies the expected type in the remote function. The targetType is the defaultable parameter that takes the expected type and its default value is http:Response.

Data types

public type Payload string|xml|json|byte[]|record {| anydata...; |}|record {| anydata...; |}[];
public type TargetType typedesc<Response|Payload>;

Remote function definition

public remote function post(string path, RequestMessage message, TargetType targetType = http:Response) returns http:Response|http:Payload|http:ClientError {}

Eg: If the user expects payload as a JSON,

json payload = <json> check clientEndpoint->post("/get?test=123", request, targetType = json);

The issue ballerina-platform/ballerina-spec#386 has mentioned this requirement and the dependently typed function signature feature as per the https://github.com/ballerina-platform/ballerina-spec/issues/426  has been introduced for external functions where contextually expected type is returned. 

But the http:Client remote functions are not 100% external where it has some ballerina level executions before calling the underneath external function. Most of the important functionalities such as caching, cookie, .. etc are written in ballerina. So if we try to make the client remote function code external, we probably have to rewrite and lose a lot of ballerina code. 

Therefore still the dependently typed function signature feature could not be used with http:Client remote functions until it supports ballerina functions(Not only external) which means the user has to do a cast in the shortened version.

http:Response response = <http:Response> check clientEndpoint->get("/sayHello");

Please check the BBE related to Client Data Binding
https://ballerina.io/swan-lake/learn/by-example/http-client-data-binding.html

Please add thoughts if there are any usability issues

[chamil321]

Therefore still the dependently typed function signature feature could not be used with http:Client remote functions until it supports ballerina functions(Not only external) which means the user has to do a cast in the shortened version.

http:Response response = <http:Response> check clientEndpoint->get("/sayHello");

Please check the BBE related to Client Data Binding
https://ballerina.io/swan-lake/learn/by-example/http-client-data-binding.html

Please add thoughts if there are any usability issues

The required changes are done via

• Remove casting from client data binding
• Add contextually expected type inference support for client methods
• Improve binding error with headers and payload

Person person = check backendClient->get("/backend/person");

Hence close the issue.