Enhancement request - simplifying API

[nstuyvesant]

Per the example kindly provided by @ekta-slit, this is how to send a transactional email:

var SibApiV3Sdk = require('sib-api-v3-sdk');

var defaultClient = SibApiV3Sdk.ApiClient.instance;
var apiKey = defaultClient.authentications['api-key'];
apiKey.apiKey = "YourApiV3Key"

var apiInstance = new SibApiV3Sdk.SMTPApi();

var sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail(); // SendSmtpEmail | Values to send a transactional email

sendSmtpEmail.to = [{ "email":"to@domain.com", "name":"toName"}];
sendSmtpEmail.sender = { "email":"sender@domain.com", "name":"sender"};
sendSmtpEmail.htmlContent = "This is test content";
sendSmtpEmail.subject = "My Subject";
sendSmtpEmail.headers = {"x-mailin-custom":"myV3Custom" };
sendSmtpEmail.tags = ["myTag1","myTag2"];
sendSmtpEmail.attachment =  [{"url": "https://example.com/ValidimageUrl1.jpg"},{"url": "https://example.com/ValidimageUrl2.jpg"}]

apiInstance.sendTransacEmail(sendSmtpEmail).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Even though this works, there's no obvious connection between SibApiV3Sdk.ApiClient.instance and SibApiV3Sdk.SMTPApi. Also, it seems like there are more steps than there should be.

Here's a mockup of how I'd like the API to work (adapted for NodeJS 10+)...

const sibApi = require('sib-api-v3-sdk');

const sendTransactionalEmailExample = async () => {
   try {
      const apiClientInstance = sibApi.ApiClient.instance;
      apiClientInstance.apiKey = 'REPLACE-WITH-YOUR-API-KEY';
      const data = await apiClientInstance.sendTransactionalEmail({
         to: [{ email: 'to@domain.com', name: 'toName' }],
         sender: { email: 'sender@domain.com', name: 'sender' },
         headers: { 'x-mailin-custom': 'myV3Custom' };
         htmlContent: 'This is test content',
         subject: 'My Subject',
         tags: ['myTag1', 'myTag2'],
         attachment: [
            { url: 'https://example.com/ValidimageUrl1.jpg' },
            { url: 'https://example.com/ValidimageUrl2.jpg' }
         ]
      });
      return data;
   } catch(err) {
      console.error(err);
      throw err;
   }
}

The main differences are:

• sendTransacEmail() renamed to sendTransactionalEmail()
• sendTransactionalEmail() is associated with require('sib-api-v3-sdk').ApiClient.instance
• The apiKey is a direct property of ApiClient.instance
• sendTransactionalEmail() provides a constructor - no need to use require('sib-api-v3-sdk').SMTPApi() or .SendSmtpEmail()
• 4 API statements to send a transactional email vs. 14 in what's needed currently.

[synoptase]

You could do something like:

var sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail(); // SendSmtpEmail | Values to send a transactional email
Object.assign(sendSmtpEmail, {
  to: [{ email: "to@domain.com", name: "toName" }],
  sender: { email: "sender@domain.com", name: "sender" },
  htmlContent: "This is test content",
  subject: "My Subject",
  headers: { "x-mailin-custom": "myV3Custom" },
  tags: ["myTag1", "myTag2"],
  attachment: [
    { url: "https://example.com/ValidimageUrl1.jpg" },
    { url: "https://example.com/ValidimageUrl2.jpg" }
  ]
});

which is a bit cleaner. Though i'm 100% behind you on all the points mentioned!

[ScreamZ]

I agree with @nstuyvesant, I think @ekta-slit used a syntax mostly based on Ruby or kind of langages which works mostly with properties. But this is not clear in doc. you need a bigger example

[shubhamUpadhyayInBlue]

Hi @nstuyvesant

I will try to answer your questions one by one:

sendTransacEmail() renamed to sendTransactionalEmail() sendTransactionalEmail() is associated with require('sib-api-v3-sdk').ApiClient.instance The apiKey is a direct property of ApiClient.instance sendTransactionalEmail() provides a constructor - no need to use require('sib-api-v3-sdk').SMTPApi() or .SendSmtpEmail() 4 API statements to send a transactional email vs. 14 in what's needed currently.

These are good suggestions that will clean the code. We will consider this point while working on code revamp. Thanks for your valuable feedback.

In response to the query to assign each key to the object individually you can assign all the keys of request payload inside a single JSON object as follows:

let defaultClient = SibApiV3Sdk.ApiClient.instance;

let apiKey = defaultClient.authentications['api-key'];
apiKey.apiKey = "YOUR API KEY";

let apiInstance = new SibApiV3Sdk.TransactionalEmailsApi();

let sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail();

sendSmtpEmail = {
    "to": [{ 
            "email":"to@domain.com", "name":"toName"
        }],
    "sender": { "email":"sender@domain.com", "name":"sender"},
    "htmlContent": "This is test content",
    "subject": "My Subject",
    "headers": {"x-mailin-custom":"myV3Custom" },
    "tags": ["myTag1","myTag2"],
    "attachment":  [{"url": "https://example.com/ValidimageUrl1.jpg"},{"url": "https://example.com/ValidimageUrl2.jpg"}]
};

apiInstance.sendTransacEmail(sendSmtpEmail).then(function(data) {
    console.log('API called successfully. Returned data: ' + data);
}, function(error) {
    console.error(error);
});```