Getting to know more about clients

Introduction

In this step, we briefly explain some clients concepts and present the clients that will be necessary for this course: analytics client and master data client. The first one will be implemented on this step, and you'll also learn how to use a client that has been already implemented in our API.

About the clients

Clients, on VTEX IO, are abstractions to other services. We tackle complexities when setting up an HTTP client, for example, so you can focus on the real value of your software. Whenever you need to set up a connection with an external API or another VTEX service, you should create a client! Some standard clients are already baked into VTEX IO, check them here.

If you already got to know more about IO services, you probably know that your implementation exports functions that receive a context object. These functions can be a resolver function to a GraphQL field, a middleware to an HTTP server or an event handler, and, in all of them, you receive a ctx (or however you wanna call it) object of type Context, and it is inside of ctx.clients where you’ll find each client.

It's possible to read more about clients concepts on this article.

Analytics client

In this course, it will be necessary to create a client that will be used to get information regarding product's number of views. The client that will be created will make a REST request in which it'll retrieve information about product views. This client needs to have a function that will be used on a handler for a specific route and this is how it can be tested.

Implementing the Analytics client and testing it

In this step, we will implement the Analytics client. So,

1. First, in the /node/clients/ directory, you will find a file called analytics.ts, which already has a sketch, just like the code block below. This is where you'll implement your client.

   ts

   //node/clients/analytics.ts
   import { AppClient } from '@vtex/api'
   
   export default class Analytics extends AppClient {}
   

   You can see in this code block that Analytics is a client that extends from AppClient because this class offers pre-configurations that assure that your client has secure communication with other parts of your app.

2. The client needs to have a constructor and just a single method, called getLiveUsers. This method returns a promise of an array that its elements are of the type LiveUsersProduct. Using the code below, add the necessary code lines to the client:

   Diff

   //node/clients/analytics.ts
   +import { AppClient, InstanceOptions, IOContext } from '@vtex/api'
   
   export default class Analytics extends AppClient {
   +  constructor(context: IOContext, options?: InstanceOptions) {
   +    super('[email protected]', context, options)
   +  }
   
   +  public getLiveUsers(): Promise<LiveUsersProduct[]> {}
   }
   
   +interface LiveUsersProduct {
   +  slug: string
   +  liveUsers: number
   +}
   

   The interface that is defined is going to be used as a typing on the method that we'll implement.

3. Now it's necessary to implement the getLiveUsers method. It returns an HTTP GET request to a well-defined endpoint that is responsible for getting the data that is needed in this application. So add the following line to the method getLiveUsers:

   ts

   return this.http.get('_v/live-products')
   

   The method that you've just created will get the necessary data for this application: an array of objects that have two fields: slug, a string that represents the product ID and liveUsers, a number that is the quantity of users visualizing this product - which are the fields in the interface.

4. The _v/live-products API endpoint we call above needs the app mocked-analytics to run, or your getLiveUsers method will not see anything there. To check if the application is already installed, run the command vtex list. If not, use the following command: vtex install vtex.mocked-analytics.

5. With your analytics client already implemented, it's necessary to declare it as one of the clients in the Clients class, so it will be accessible using the Context that we've talked about at the beginning of this step.

   So, in the node/clients/ directory, go to the file called index.ts and add a get method to the class that refers to the analytics client. It's also necessary to import the client that you created.

   Diff

   // node/clients/index.ts
   + import Analytics from '../clients/analytics'
   
   export class Clients extends IOClients {
   +  public get analytics() {
   +    return this.getOrSet('analytics', Analytics)
     }
   }
   

6. So as to see it working, it's possible to use getLiveUsers method inside the handler for the analytics client. Using a route that it's already defined in the project, it is possible to send a request to it and the handler responsible for this route will call the method that we created.

   Inside the node directory, there is a folder called handlers. There is already a file named analytics.ts, in which it's necessary to do two things for your test to work: get the analytics client from ctx and replace the content of ctx.body with the method mentioned before, as you can see in the code block below:

   Diff

   export async function analytics(ctx: Context, next: () => Promise<any>) {
   +  const {
   +    clients: { analytics },
   +  } = ctx
   +  ctx.status = 200
   -  ctx.body = 'OK'
   +  ctx.body = await analytics.getLiveUsers()
   +  ctx.set('cache-control', 'no-cache')
      await next()
   }
   

7. Now let's test it! It's possible to use Postman to send a GET request to the following route:

   {your workspace}--{your account}.myvtex.com/_v/app/analytics/realTime

   and it's expected that it replies with the data and status 200.

   Attention! Generally, the account where you're running the app is appliancetheme.

Any questions?

See the answersheet for this step or check our [office hours] on the VTEX Developers channel(https://www.youtube.com/c/VTEXDevelopers)