Products and Thngs

In this section we will create a product resource to represent the product SKU used in the product scanning scenario, from which all Thng instances of the product will be associated and so will share the same metadata. After that, we will add some Thngs to represent those individual product instances. It is these individual instances being engaged with by separate users that will be 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, etc.

We will create a product now 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 in question will be a fictitious box of cereal that will have a consumer engagement experience attached to it via a user-scannable QR code.

Product creation is done using a POST /products request. At the same time, we will make sure it is scoped to the correct project using the project query parameter set 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 modelling the use-case 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 so 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 will suffice for this purpose. An important component is the product property - this 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 will introduce the concepts of redirections and actions that will be used to provide the consumer engagement experience and provide a mechanism to track and analyse user activity.