Projects and Applications

In this section we will create a project and application to help scope and model the data for this scenario. The project will contain all the resources relevant to this API walkthrough, whereas the application will represent a mobile app that will interact with the data uploaded by the device.

Creating a Project

A project is the top-most level of scoping in an EVRYTHNG account. By scoping individual resources to different projects, you can control who has access to them, separate concerns, and easily view only resources that are relevant to the project. To create your first project, make a POST /projects request and include the required fields in the payload:

📘

Note

If you have not exported OPERATOR_API_KEY in your terminal session environment, remember to replace this in the subsequent examples.

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/projects' \
  -d '{
    "name": "Weather Station Project",
    "description": "A project for all the API walkthrough weather station resources.",
    "tags": [ "Connected Devices" ]
  }'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UmCa6NYaVDswQpwRaD4sGtMs",
  "createdAt": 1498467696237,
  "tags": [
    "Connected Devices"
  ],
  "name": "Weather Station Project",
  "description": "A project for all the API walkthrough weather station resources.",
  "shortDomains": [
    "tn.gg"
  ]
}

The response will contain an id field, which is the project’s unique identifier. Make a note of this now for use in the rest of this walkthrough. To read it again in the future, make a GET /projects request:

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/projects'

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UmCa6NYaVDswQpwRaD4sGtMs",
    "createdAt": 1498467696237,
    "customFields": {},
    "tags": [
      "Connected Devices"
    ],
    "name": "Weather Station Project",
    "description": "A project for all the API walkthrough weather station resources.",
    "shortDomains": [
      "tn.gg"
    ]
  }
]

With this newly created project we can correctly scope future resources created in this API walkthrough to keep them tidily all in one place. This is usually done by including the project query parameter, as you will see in the upcoming examples.

## Creating an Application

Every project in the Platform, such as the one you just created, can contain one or more application resources. Whereas a project resource helps scope resources, applications help manage access to resources. For example, access can be given to individual Application Users, who can each be given their own Application User API Key with access to only those resources in the project they are scoped to.

The application resource itself is most commonly used to model the interactions with the Platform resources through a mobile or web application, and contains a special Application API Key to let the third-party app make requests with the right level of access. You will obtain one of these below.

Creating an application through the API is done by making a POST /projects/:projectId/applications request, which requires the ID of the project the application will belong to. Use the noted ID from the POST /projects response, or make a GET /projects request to find it again.

Substitutions: :projectId

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/projects/:projectId/applications' \
  -d '{
    "name": "Weather Station Mobile App",
    "description": "A mobile app to manage weather stations.",
    "socialNetworks": {}
  }'

HTTP/1.1 201 Created
Content-Type: applicatin/json

{
  "id": "UmCa68aRBgPw95wwwDnPpmEb",
  "createdAt": 1498467840882,
  "updatedAt": 1498467840882,
  "name": "Weather Station Mobile App",
  "description": "A mobile app to manage weather stations.",
  "project": "UmCa6NYaVDswQpwRaD4sGtMs",
  "socialNetworks": {},
  "appApiKey": "aUTg2u1lKMedmZDcXTTqM1Ogq1k1kLt32Jf54x4TLat...",
  "defaultRole": "base_app_user"
}

Make a note of the appApiKey - this is the Application API Key, and is used to allow mobile or web applications to interact with the Platform resources, as well as to create and manage Application Users. These users will be the ones creating and managing their own resources representing products and things. We will cover all this in the next sections.