Re-Design the gmail connector APIs

[niveathika]

Currently the connector supports remote method.

In this redesign we have to look into designing the connector with resource method. There are many advantages to this,

1. The underlying API is exposed w/o much complication
2. Developer friendly
3. Using open API spec to design this leads to low maintainability in the future

[niveathika]

During the initial design process, I found out that gmail REST API includes users in the resource path,

url : https://gmail.googleapis.com/gmail/v1
GET /users/{userId}/messages

This is a special case as the userId is constant for an authenticated user. For instance, If a user A@gmail.com has authenticated using OAuth2 app, the only values for userId is either me or A@gmail.com. When designing the ballerina API client, the userId can be an initialisation variable as this will not change for each client. (Authentication details are tied to the client).

However this approach is not yet supported by our openapi to ballerina tool as tracked in #5056. If we were to follow this approach, we have to write the client by hand, which will lead to high maintenance. After this discussion offline, we have decided to keep the /users/{userId}/messages resource path for now.

[niveathika]

I have noticed visible drop in usability in generated clients. For instance looking at a common scenario of processing mail details,

v3.5.0

gmail:MessageRequest message = {
        recipient: recipient, // Recipient's email address
        sender: sender, // Sender's email address
        subject: "Gmail Connector Revamp",
        messageBody: "Test sending mails!!!! ",
        contentType: "text/plain"
};
gmail:Message _ = check gmailClient->sendMessage(message);

Full Code - https://gist.github.com/niveathika/adde8c1304d3e3ed31a4f253fb2b3cb2

v4.0.0 (Generated from OAS)

string rawMessage = string
`To:${message.recipient}
Subject:${message.subject}
From:${message.sender ?: "me"}
Content-Type:text/plain;charset="UTF-8"

${message.messageBody}`;

string encodedMessage = array:toBase64(rawMessage.toBytes());
encodedMessage = re `\+`.replaceAll(encodedMessage, "-");
encodedMessage = re `/`.replaceAll(encodedMessage, "_");

gmail:Message _ = check gmailClient->sendMessage("me", {raw: encodedMessage});

Full Code - https://gist.github.com/niveathika/b65e40744ca3354e7b651c7e9fda3bdc

As you can see from the above code, users need to know how to create a message(mail) in RFC822 format before invoking the API. This is a common problem seen across multiple APIs.

[niveathika]

POC to solve the usability drop is tracked in #5103

[niveathika]

As per the PoC, we can go ahead with wrapper client to the OAS generated client.

[niveathika]

The design document can be found in https://docs.google.com/document/d/1AP8TbXXwrKSsruvllGDiCmt5zndmCzEukxwtM6DKCh4/edit#heading=h.qeyhtzaqlx4s

[niveathika]

Closing as the design is accepted and we will move to implementation