# Quick Start Guide

This guide will help you craft your first API calls with Nacelle. This guide will take approximately ten minutes to complete.

# Prerequisites

All you need is your favorite API client. We love Insomnia but Postman is a good alternative.

# Create a Nacelle Space

A Space is a container where your product and content data is synchronized with Nacelle's systems. It is organized into indices for products, product collections, and content so that it can be immediately and reliably be served to your storefront.

# Register

We will start by creating a Nacelle account. Navigate to the dashboard and create an account. Upon registering, you will be greeted with the getting started walk-through. Click the "Create Space" button to proceed.

# Space Setup

For this quick start guide, we will send product data via API calls. Your product information management (PIM) will need to have a unique URL. When your product data is indexed with the Data Ingestion API, this "PIM domain" is used to identify the product data uniquely. If you are unsure what to put here, use pim.merchant.com and replace "merchant" with your domain. Repeat this for the content prompts.

For the checkout, click "Skip. I'll do this later". You can go back into your settings to change this at any point in the future.

# Data Ingestion API

Now that our Space has been created let's send some data into the Data Ingestion API. Nacelle leverages GraphQL APIs, which you can learn about at https://graphql.org/.

Under the "API" tab of the Nacelle dashboard, you can find your Data Ingestion Endpoint. Setup a POST call to this endpoint with the following headers:

Content-Type: application/json
x-nacelle-space-id: <your space ID here>
x-nacelle-space-token: <your private token here>

If you are using an API client like Insomnia, you can now click "show documentation" to see the Data Ingestion GraphQL schema.

# Index a Product

Use the indexProducts mutation to send product create and product update events to Nacelle. This API request is similar to other "create or update" methods, but Nacelle keys on the product handle attribute. You will need to place two objects into the input parameter for this mutation, the pim and the products.

Below is an example of the fully formed indexMutation API call. You can copy and paste this directly into your API client and then send the mutation (be sure to add in your own PIM domain!):

mutation IndexProduct {
  indexProducts(
    input: {
      pim: {
        syncSource: "custom"
        syncSourceDomain: "<put your pim domain here>"
        defaultLocale: "en-us"
      }
      products: [
        {
          handle: "phaser-gun"
          locale: "en-us"
          pimSyncSourceProductId: "phsr782"
          title: "Original Phase Gun"
          description: "The most common and standard direct energy weapon in the arsenal of Starfleet. Classified as a particle weapon"
          availableForSale: false
        }
      ]
    }
  ) {
    count
    ids
  }
}

The response to your request should look like:

{
  "data": {
    "indexProducts": {
      "count": 1,
      "ids": ["your-pim-domain::phaser-gun::en-us"]
    }
  }
}

This response is simply a recognition that Nacelle received the creation event of the product. However, being an async event, the successful Data Ingestion Engine response does not guarantee successful indexing (saving) of that data.

# Storefront API

Now that our Space has a product in it let's fetch it with a query. You can find the Storefront endpoint under the "API" tab of the Nacelle dashboard. Setup a POST call to this endpoint with the following headers:

Content-Type: application/json
x-nacelle-space-id: <your space ID here>
x-nacelle-space-token: <your public token here>

Note: be sure to use the correct space token for the Storefront API (this is your public token)

If you are using an API client like Insomnia, you can click "show documentation" to see the Storefront API schema.

# Query your First Product

Use the getProductByHandle query to fetch a product from the Storefront API. You can copy and paste the following directly into your API client and then send the query.

query getProduct {
  getProductByHandle(handle: "phaser-gun") {
    id
    handle
    locale
    title
    description
    availableForSale
  }
}

You should receive a response to your request:

{
  "data": {
    "getProductByHandle": {
      "handle": "phaser-gun",
      "locale": "en-us",
      "title": "Original Phase Gun",
      "description": "The most common and standard direct energy weapon in the arsenal of Starfleet. Classified as a particle weapon",
      "availableForSale": false
    }
  }
}

Nice work, you've sent a product into Nacelle using the Data Ingestion API, then queried for it using the Storefront API. Let's continue our exploration of the Data Ingestion Engine.

# Multiple Products

Return to the Data Ingestion indexProducts mutation and, this time, add two products to the array. One will be the Phaser Gun we already made. Here, we will change the availability from false to true. The second will be a new product. Be sure to add in your own PIM domain!

mutation IndexProduct {
  indexProducts(
    input: {
      pim: {
        syncSource: "custom"
        syncSourceDomain: "<your-pim-source-domain>"
        defaultLocale: "en-us"
      }
      products: [
        {
          handle: "phaser-gun"
          locale: "en-us"
          pimSyncSourceProductId: "phsr782"
          title: "Original Phase Gun"
          description: "The most common and standard direct energy weapon in the arsenal of Starfleet. Classified as a particle weapon"
          availableForSale: true
        }
        {
          handle: "food-replicator"
          locale: "en-us"
          pimSyncSourceProductId: "foodprint1701"
          title: "Food Replicator"
          description: "A molecule synthesizer that uses anti-matter conversion technology. Used to feed the crew."
          availableForSale: true
        }
      ]
    }
  ) {
    count
    ids
  }
}

This time our response will show two objects which have been successfully received.

Let's switch to the Storefront API and use the getProducts query to fetch both products.

query getProducts {
  getProducts(first: 100) {
    items {
      handle
      availableForSale
      title
      description
      availableForSale
    }
  }
}

The results will show both products; the new Food Replicator and the previously indexed Phaser Gun, which is now available for sale.

# Mission Complete

Congratulations! You have successfully executed your first few API calls with Nacelle.

We recommend having a look at all of the Product, Collection, and Content API calls available in the Data Ingestion API Reference. If you use Shopify, you can skip the backend API calls and jump directly to the Shopify Guide.

Curious what you can build on top of our Storefront API? Head to the Storefront Development section of the docs, where we discuss building PWA storefronts that provide superior shopping experiences for your customers. Vue, React, Preact, Svelte, we love it all!