Getting to know more about clients
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
Analytics
client and testing itIn this step, we will implement the Analytics client. So,
-
First, in the
/node/clients/
directory, you will find a file calledanalytics.ts
, which already has a sketch, just like the code block below. This is where you'll implement your client.//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 fromAppClient
because this class offers pre-configurations that assure that your client has secure communication with other parts of your app. -
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 typeLiveUsersProduct
. Using the code below, add the necessary code lines to the client://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.
-
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 methodgetLiveUsers
: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 andliveUsers
, a number that is the quantity of users visualizing this product - which are the fields in the interface. -
The
_v/live-products
API endpoint we call above needs the appmocked-analytics
to run, or yourgetLiveUsers
method will not see anything there. To check if the application is already installed, run the commandvtex list
. If not, use the following command:vtex install vtex.mocked-analytics
. -
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 theContext
that we've talked about at the beginning of this step.So, in the
node/clients/
directory, go to the file calledindex.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.// node/clients/index.ts + import Analytics from '../clients/analytics' export class Clients extends IOClients { + public get analytics() { + return this.getOrSet('analytics', Analytics) } }
-
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 namedanalytics.ts
, in which it's necessary to do two things for your test to work: get the analytics client fromctx
and replace the content ofctx.body
with the method mentioned before, as you can see in the code block below: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() }
-
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)
Help us make this content better!
VTEX IO courses are open source. If you see something wrong, you can open a pull request!
Make a contributionUpdated 9 months ago