Running Your Own Petshop
Downloading and Running the Code
As the first step before any hacking, let’s get you up and running with a local instance of the Petshop.
Prerequisites
The Petshop is implemented as a lightweight Node.js application hosted on Github. Please make sure that the node
and npm
commands are available on your machine.
Aside from that, you only need a decent code editor of your choice, such as the excellent and free Visual Studio Code.
Downloading the Code and Dependencies
Assuming you have Git installed, it’s easiest to download the application and all needed packages from your terminal window. You can also download the repository as a Zip file from GitHub.
git clone https://github.com/DynamicYield/api-tutorial-petshop.git
cd api-tutorial-petshop
cd before
npm install
At the top level of the repository, you will find two directories:
before
includes a clean version of the website, before integrating any Dynamic Yield code. This is the version you will use throughout the tutorial.after
contains the website as it will be at end of tutorial, with all steps executed already. If you just want to see how the end results looks like, you can run that revision.
Running the Server
Start the server with the npm start
command. The output should look similar to this:
Now, open your favorite browser and navigate to http://localhost:3000, and you'll get the homepage of our little Petshop.
The server is listening to code changes!
There is no need to restart the server after each code change that you make, as your development server is listening to any changes in code and will automatically reload what's needed.
Getting Familiar with the Code
Before we start making changes, let's take a few minutes to review the structure of the application.
For this tutorial, we made a conscious choice not to use any hot framework of the day, and keep it pretty old school in order to concentrate on the needed code changes rather than the intricacies of a specific opinionated framework.
As a common way to run web servers with Node.js, we chose Express. All views are rendered on the server-side with pug.
app.js
This should be your entry point to diving into the code. This is where the Express app
object is initialized and configured through the middleware pattern - note the usage of app.use(...)
for adding middleware.
This code is all pretty standard stuff, but here's one thing that is worth your attention: as part of all calls to our API endpoint, we ask that you pass a userId and a sessionId. The userId should be a long-term identifier of the device, while the sessionId should designate a time-limited period of activity.
In this application, we went with pretty simple solution: the userId is stored as a cookie with a 1-year TTL (and you may want to extend its lifetime on each user visit). The sessionId is managed within a session cookie.
/** userId management */
app.use((req, res, next) => {
let { userId } = req.cookies;
if (!userId) {
userId = uuidv4();
res.cookie('userId', userId, { maxAge: 365 * 24 * 60 * 60 * 1000, httpOnly: true });
}
req.userId = userId;
next();
});
/** session management */
app.use(cookieSession({
name: 'session',
secret: 'somesecretkeyhash',
}));
app.use((req, _res, next) => {
if (req.session.isNew) { // cookieSession defines what is considered a new session
req.session.sessionId = uuidv4();
}
req.sessionId = req.session.sessionId;
// ...
next();
});
Using Session Cookies
Using a session cookie for managing the lifetime of a session ID is pretty common and a reasonable choice, but note that the logic by which a browser determines whether a new session gets created is specific to the browser and device. Alternatively, you can decide to manage sessions yourself based on your needs, across platforms.
Routes and Views
The routes
directory is where server-side handlers are located for each route in the application, such as /homepage, /category etc.
Templates are within views
, rendered server-side with the pug.js engine. The layout.pug
template is rendered as part of all pages in the application.
Within the public/javascripts/
directory, please also note the client-side Javascript modules which are included in all rendered pages.
The Product Feed
So, where are the silly products in this shop coming from?
Take a look at the file feed/products.json
. It contains all details of the available products, and gets loaded by the Product model (models/product.js
). We will later upload that very file into Dynamic Yield as the product feed to use, making it available for recommendations, targeting and many more features which rely on this data.
But, let's not worry about that just yet 😉. First, we should create a new Site entity via the Dynamic Yield Admin UI, and an API key for securely calling any API endpoints.
Updated about 1 year ago