Lana Docs - Tutorial

This tutorial will guide you through the basics of using the JSON API with NodeJS. Prior knowledge of basic Linux shell commands, NodeJS, npm, TypeScript, and JavaScript is assumed.

Start by creating a new npm project:


# Create a new directory for your project
mkdir test-json-api
# Navigate into your new project directory
cd test-json-api
# Initialize a new npm project
npm init
# Press 'Enter' multiple times to accept the defaults

Install the necessary dependencies:
- TypeScript compiler.
- Lana-specific core library (provides json client helper library).
- Optionally, install the "cross-fetch" package if your older NodeJS version doesn't support the "fetch()" API.
```
npm install -D typescript @lana-commerce/core cross-fetch
```

Initialize the TypeScript configuration:


npm exec -- tsc --init

Create a basic script by saving the following content as main.ts:


// Import the cross-fetch polyfill only if your NodeJS version doesn't support the "fetch()" API
import "cross-fetch/polyfill";
// Import necessary functions from the core library
import { request, prettyPrintResponseError } from "@lana-commerce/core/json/storefront";
async function main() {
  // Send a GET request to the "info/countries.json" endpoint
  const response = await request({}, "GET:info/countries.json").send();
  // Throw an error if the response does not contain data
  if (response.kind !== "data") {
    throw new Error(prettyPrintResponseError(response));
  }
  // Loop over the data in the response and print each country's code and name
  for (const c of response.data) {
    console.log(`CODE: ${c.code}, NAME: ${c.name}`);
  }
}
// Call the main function
main();

Compile and run the script:


npm exec -- tsc
node main.js

If successful, the script will print a list of countries:


CODE: AD, NAME: Andorra
CODE: AE, NAME: United Arab Emirates
CODE: AF, NAME: Afghanistan
CODE: AG, NAME: Antigua and Barbuda
...
CODE: YT, NAME: Mayotte
CODE: ZA, NAME: South Africa
CODE: ZM, NAME: Zambia
CODE: ZW, NAME: Zimbabwe

Congratulations! You have successfully written a simple script that uses the Lana JSON API. The next steps are optional, but recommended for a deeper understanding.

To further challenge yourself, try a query with variables. Add the following code to the end of the main() function in the main.ts script:


const response2 = await request({}, "GET:info/provinces.json").country_code("XX").send();
if (response2.kind !== "data") {
  throw new Error(prettyPrintResponseError(response2, true));
}
for (const p of response2.data) {
  console.log(`PROVINCE CODE: ${p.code}, NAME: ${p.name}`);
}

Note that a non-existent country code is used here intentionally. Compiling and running this script will result in an error. Also, note the detailed flag set to true in the prettyPrintResponseError() function call. This flag prompts the function to print more detailed error information.

Compile and run the script:


npm exec -- tsc
node main.js

In addition to your list of countries, you should see an exception thrown with a message that looks somewhat like this:


Error: JSON API request failed:
Url: https://api.lana.dev/relay.json
Path: info/provinces.json?country_code=XX
Status: 400
IdempotencyKey: f389cbf4-b849-4c2d-8557-57ec15b78bf9
[NotFound] Not Found

Try changing the country code to a valid one and run the script again. Remember to compile your code before running it!
End of the tutorial.

Commerce or Storefront API

This tutorial uses Storefront API. If you want to work with Commerce API you need to perform the following changes:

Replace the following import statement:


import { request, prettyPrintResponseError } from "@lana-commerce/core/json/storefront";

with:


import { request, prettyPrintResponseError } from "@lana-commerce/core/json/commerce";

PREVIOUS
Introduction

NEXT
Pagination