Products and Application Users

In this section we will create a product resource to represent the product SKU in the inventory management scenario, from which all instances of the product can be created and will share the same metadata. After that, we will add an Application User who will create and manage the Thngs they are responsible for.


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 supply chain will deal in. This is done using a POST /products request. At the same time, we will make sure it is scoped to the correct project to limit visibility using the project query parameter and the project ID.

Substitutions: :projectId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/products?project=:projectId' \
  -d '{
    "name": "Honeysuckle Zombie Brown Ale",
    "description": "A delicious animating local beer for export.",
    "tags": ["export"]
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "U3EtU2k3BD8wQpwwR6EMXgKb",
  "createdAt": 1501509769311,
  "updatedAt": 1501509769311,
  "properties": {},
  "description": "A delicious animating local beer for export.",
  "fn": "Honeysuckle Zombie Brown Ale",
  "name": "Honeysuckle Zombie Brown Ale",
  "tags": ["export"]
}

Creating an Application User

Now that the account, project, application, and product resources modelling the supply chain have been created, we need to create additional Platform resources to model the bottles of beer themselves. Since these will belong to/be managed by users of the mobile app, the requests to the API should be authenticated with the user’s Application User API Key, which has more appropriate sets of permissions centered around managing individual resources. In a real-world scenario, this change in authentication key represents the user creating their own Thngs after logging into the management mobile app, perhaps after scanning an object’s barcode.

Create an Application User using the Application API Key you made a note of earlier, or use a GET projects/:projectId/applications request to find it again. Make a POST /auth/evrythng/users request to create the user resource. Each user must supply at least their first name, last name, an email address, and a password, but can contain much more information.

curl -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://api.evrythng.com/auth/evrythng/users' \
  -d '{
    "firstName": "Sean",
    "lastName": "Angle",
    "email": "[email protected]",
    "password": "passw0rd"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "evrythngUser": "U3EQA4aDeXPwQpwRagPwMMhb",
  "activationCode": "DIlB8k6F",
  "status": "inactive",
  "email": "[email protected]"
}

This is a two part process, in which the Application User will not receive an Application User API Key until their account is validated. In a real-world application, this is commonly achieved using a verification email, but for now, we will do this immediately using the API.

The Application User is validated by returning the activationCode value from the response to the API in a POST /auth/evrythng/users/:evrythngUser/validate request. Once this is done, the user will receive an Application User API Key that they can use to make requests on their own behalf.

Substitutions: :evrythngUser, :activationCode

curl -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://api.evrythng.com/auth/evrythng/users/:evrythngUser/validate' \
  -d '{
    "activationCode": ":activationCode"
  }'
HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "active",
  "evrythngUser": "U3EQA4aDeXPwQpwRagPwMMhb",
  "evrythngApiKey": "S68QqT4sQ8A49XnPMOZ0WS3ZqpF1mOACYhhea42XJ..."
}

The Application User is now activated, and their Application User API Key can be seen in the final response. This is the API key to use to manage resources that user should see and interact with within the project. Make a note of this API key now. We will use it in the next section.