Projects

Every account may contain one or more projects. A project is a container for applications and Application Users, and provides an easy way to share and work with a subset of the resources that exist in an account through Scoping.

Projects are their own scope; every resource may or may not be part of the project scope, which in turn limits visibility of those items to only that project. For more details about scoping, see Scoping.

API Status
General Availability:
/projects
/projects/:projectId

Jump To ↓

ProjectDocument Data Model
Create a Project
Read a Project
Real all Projects
Update a Project
Delete a Project

ProjectDocument Data Model

.name (string, required)
    Friendly name of this resource.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.tags (array of string)
    Array of string tags associated with this resource.

.description (string)
    Friendly description of this resource.

.startsAt (integer)
    Timestamp when this project starts.

.endsAt (integer)
    Timestamp when this project ends.

.imageUrl (string)
    URL link to the image to use in the project properties view.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.shortDomains (array of string)
    An array of short domains assigned for the project, for 
    example: `tn.gg` by default.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing a platform project.",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "startsAt": {
      "type": "integer",
      "description": "Timestamp when this project starts."
    },
    "endsAt": {
      "type": "integer",
      "description": "Timestamp when this project ends."
    },
    "imageUrl": {
      "type": "string",
      "description": "URL link to the image to use in the project properties view."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "shortDomains": {
      "type": "array",
      "description": "An array of short domains assigned for the project, for example: `tn.gg` by default.",
      "items": { "type": "string" }
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["identifiers.<key>", "name", "tags"]
}

{
  "id": "U4aPM5gyBg8w9pwaaYKCepVg",
  "createdAt": 1510919010607,
  "updatedAt": 1510919010607,
  "name": "European Region",
  "description": "A project for all resources in Europe",
  "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/8/84/Example.svg",
  "startsAt": 1510918931000,
  "endsAt": 1542454931000,
  "shortDomains": [
    "tn.gg"
  ],
  "customFields": {
    "region": "europe"
  }
}

Filterable Fields

This resource type can be filtered using the following fields and operators.

Field	Type	Operators
`name`	String	`=`
`identifiers.<key>`	String	`=`
`tags`	List of string	`=`

Create a Project

Create a new project within an account.

POST /projects
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ProjectDocument

curl -i -H "Content-type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/projects' \
  -d '{
    "name": "European Region",
    "description": "A project for all resources in Europe",
    "customFields": {
      "region": "europe"
    }
  }'

const payload = {
  name: 'European Region',
  description: 'A project for all resources in Europe',
  customFields: {
    region: 'europe'
  }
};

operator.project().create(payload)
  .then(console.log);

Project project = new Project();
project.setName("European Region");
apiManager.projectService().projectCreator(project).execute();

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://$EVT_API_DOMAIN/projects/UNwYkFVG9ef4wEwwap9XFqpn

{
  "id": "UNwYkFVG9ef4wEwwap9XFqpn",
  "createdAt": 1560774729291,
  "customFields": {
    "region": "europe"
  },
  "updatedAt": 1560774729291,
  "name": "European Region",
  "description": "A project for all resources in Europe",
  "shortDomains": [
    "tn.gg"
  ]
}

Read a Project

Gets a single project by its projectId.

GET /projects/:projectId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/projects/UNwYkFVG9ef4wEwwap9XFqpn'

const projectId = 'UNwYkFVG9ef4wEwwap9XFqpn';

operator.project(projectId).read()
  .then(console.log);

String projectId = "UNwYkFVG9ef4wEwwap9XFqpn";

Project project = apiManager.projectService().projectReader(projectId).execute();

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

{
  "id": "UNwYkFVG9ef4wEwwap9XFqpn",
  "createdAt": 1560774729291,
  "customFields": {
    "region": "europe"
  },
  "updatedAt": 1560774729291,
  "name": "European Region",
  "description": "A project for all resources in Europe",
  "shortDomains": [
    "tn.gg"
  ]
}

Read all Projects

Read all projects in an account. The result may be paginated if there are more than 30 items.

GET /projects
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/projects'

operator.project().read()
  .then(console.log);

List<Project> projects = apiManager.projectService().projectsReader().list().getResult();
for(Project project : projects) {
    System.out.println(project.toString());
}

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

[
  {
    "id": "UNwYkFVG9ef4wEwwap9XFqpn",
    "createdAt": 1560774729291,
    "customFields": {
      "region": "europe"
    },
    "updatedAt": 1560774729291,
    "name": "European Region",
    "description": "A project for all resources in Europe",
    "shortDomains": [
      "tn.gg"
    ]
  }
]

Update a Project

Update the fields of a project by its id by POSTing a subset of the ProjectDocument containing the changed fields.

PUT /projects/:projectId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ProjectDocument (subset)

curl -i -H "Content-type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/projects/UEqs3aV3NyYGVRxhmnphVGdh' \
  -d '{ 
    "name": "American Region",
    "customFields": {
      "region": "america"
    }
  }'

const projectId = 'UEqs3aV3NyYGVRxhmnphVGdh';
const payload = {
  name: 'American Region',
  customFields: {
    region: 'america'
  }
};

operator.project(projectId).update(payload)
  .then(console.log);

String projectId = "UEqs3aV3NyYGVRxhmnphVGdh";

Project project = apiManager.projectService().projectReader(projectId).execute();
project.setName("American Region");

apiManager.projectService().projectUpdater(projectId, project).execute();

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

{
  "id": "UNwYkFVG9ef4wEwwap9XFqpn",
  "createdAt": 1560774729291,
  "customFields": {
      "region": "america"
    }
  "updatedAt": 1560774729291,
  "name": "America Region",
  "description": "A project for all resources in Europe",
  "shortDomains": [
    "tn.gg"
  ]
}

Delete a Project

Delete a project by its id. This will also remove access to any contained applications, Application Users, etc.

❗️
Danger
This action cannot be reversed! You will lose access to ALL applications and Application Users within the deleted project.

DELETE /projects/:projectId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/projects/UEqs3aV3NyYGVRxhmnphVGdh'

const projectId = 'UEqs3aV3NyYGVRxhmnphVGdh';

operator.project(projectId).delete()
  .then(() => console.log('Project deleted'));

String projectId = "UEqs3aV3NyYGVRxhmnphVGdh";

apiManager.projectService().projectDeleter(projectId).execute();

HTTP/1.1 200 OK

ProjectDocument Data Model

Filterable Fields

Create a Project

Read a Project

Read all Projects

Update a Project

Delete a Project

❗️Danger

❗️
Danger