Products and Thngs

In this section, you create a product resource to represent the product SKU used in the product scanning scenario from which all Thng instances of the product are associated and share metadata. After that, you add some Thngs to represent those individual product instances. It is these individual instances, being engaged with by separate users, that are key in providing consumer engagement behavior insights.


Creating a Product

Product resources are used to model classes of objects, and can be thought of as SKU-level data, or an object template. Products should contain all data that is common to all instances of the object type they represent, such as size, weight, color, model number, barcodes, and so on.

Create a product using the Operator API Key (as the manager of the account) to represent the type of product the consumers will be scanning. In this example, the product is a fictitious box of cereal that has a consumer engagement experience attached to it via a user-scannable QR code.

Product creation is done using a POST /products request. Make sure it's scoped to the correct project by setting the project query parameter to the project ID.

Substitutions: :projectId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.io/v2/products?project=:projectId' \
  -d '{
    "name": "Super Crunchy Cereal",
    "description": "Like regular cereal, but extra crunchy.",
    "tags": ["engagement"]
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "U4MUfRpBVDPRt5aaaFVC2dgp",
  "createdAt": 1522749620121,
  "tags": [
    "engagement"
  ],
  "updatedAt": 1522749620121,
  "description": "Like regular cereal, but extra crunchy.",
  "fn": "Super Crunchy Cereal",
  "name": "Super Crunchy Cereal"
}

Creating Some Thngs

Now that the account, project, application, and product resources have been created, we need to create some serialized resources to model the boxes of cereal themselves. Thngs represent single instances of a class of objects and should be created with a link to the product resource representing their SKU.

To create the first Thng, send a POST /thngs request with an appropriate API key; the previously used Operator API Key suffices for this purpose. An important component is the product property, which links the individual Thng to its product class resource.

Since these Thngs will belong to the same project as the scanning web application, the requests to the API should include the project query parameter to keep them within the same project scope.

Substitutions: :projectId, :productId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.io/v2/thngs?project=:projectId' \
  -d '{
    "name": "Super Crunchy #34871",
    "description": "A single box of Super Crunchy Cereal.",
    "product": ":productId"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UnqdWBqkVXPwQpwaa2emyrAe",
  "createdAt": 1522750664432,
  "updatedAt": 1522750664432,
  "name": "Super Crunchy #34871",
  "description": "A single box of Super Crunchy Cereal.",
  "product": "U4MUfRpBVDPRt5aaaFVC2dgp"
}

Lastly, create a few more Thngs (say, five) for additional boxes of cereal in order to flesh out the example project to include more individual items. Increment the number in each name value to tell them apart:

  • Super Crunchy #34871
  • Super Crunchy #34872
  • Super Crunchy #34873
  • Super Crunchy #34874
  • Super Crunchy #34875
  • Super Crunchy #34876

The next section introduces the concepts of redirections and actions that are used to provide the consumer engagement experience and provide a mechanism to track and analyze user activity.