Structuring of an API class?

[bilogic]

Hi,

Suppose our app needs to access the PayPal API,

1. What kind of class will it be?
2. For most API, there is a usual login, getting a token and calling the various functions with the token, how do we structure this in LUCID?

Thank you.

[Mulkave]

1. First of all since PayPal is going to be an integration point this means that you would have a Domain in that name
2. Create a Client class that is responsible for the communication with PayPal API Domains/PayPal/PayPalClient.php

In this class you would have methods such as PayPalClient::authenticate, PayPalClient::send($url, $params) etc. (you'd know better regarding the methods here based on your use case.

3. Create a job for each functionality required, even if they call the same method from PayPalClient with different parameters. For example this would be Domains/PayPal/Jobs/AuthenticateWithPayPal:

use App\Data\PayPal\Token;
use App\Domains\PayPal\PayPalClient;

class AuthenticateWithPayPalJob
{
   public function handle(PayPalClient $client): Token
   {
      $response = $client->authenticate(...);
      // parse response into a Token object
      return Token::makeFromResponse($response);
   }
}

To deal with the token there are two approaches:

1. Stateful: Client keeps state of the token, if it doesn't find one it fetches it and caches it in a property
2. Stateless: Client that just returns the token and you'd use it as parameter in each job which then passes it to the client

I know these examples may be irrelevant but i hope it helps 😅

[bilogic]

Do you mean it will look like below?

class CheckBalanceFeature
{
    function handle()
    {
        $ppc = new \Domains\PayPal\PayPalClient($username, $password);
        $token = $this->run(AuthenticateWithPayPalJob::class, ["PayPalClient" => $ppc]);

        $this->run(CheckBalancePayPalJob::class, ["token" => $token]);
    }
}

In other words, we will not have $PayPalClient->authenticate($username, $password), correct?

[Mulkave]

Yes, very close! I can suggest a few enhancements to the above:

1. In a feature, only call jobs and operation. Never a direct class (i.e. PayPalClient)
2. No need to pass the client to AuthenticateWithPayPalJob because it already knows which class it needs to deal with
3. Exchange objects between jobs instead of primitive data types (strings, numbers, etc.)

Here's how it would look like after the above (though not sure if i understand correctly whether you should or should not have username and password).

class CheckBalanceFeature
{
    public function handle()
    {
        $token = $this->run(AuthenticateWithPayPalJob::class, [
           'username' => $username,
           'password' => $password,
        ]);

        $this->run(CheckPayPalBalanceJob::class, compact('token'));
    }
}

And in AuthenticateWithPayPalJob we inject the client and authenticate:

class AuthenticateWithPayPalJob
{
    private $username;
    private $password;

    public function __construct(string $username, string $password)
    {
        $this->username = $username;
        $this->password = $password;
    }

    public function handle(PayPalClient $client)
    {
        return $client->authenticate($this->username, $this->password);
    }
}

[bilogic]

Hmm... interesting.
Perhaps you could include such examples in the repo, it might gain a bigger following to LUCID.

Thanks.