A hands-on tutorial for the SocioCortex REST-API.

1. Introduction

1.1. Motivation

Social information management involves multiple users collaborating in the design and creation of information. More than 10 years of research and cooperations with industry partners in this area revealed recurring problems and solution patterns. Therefore, social information management systems share a common set of general capabilities and features.

SocioCortex integrates those features and exposes them as services to its applications. In this way, domain-specific applications built upon the SocioCortex platform benefit from proven solution patterns for prevalent social information management problems.

App developers can build custom apps faster using the rich REST-API of the SocioCortex platform.

In order to spur the use of the REST-API and to remove barriers, this tutorial provides a hands-on example covering most of the typical use cases relevant for developers.

1.2. Concepts

1.2.1. Architecture

The image below illustrates the layers the SocioCortex REST-API is built of:

Architecture layers
Figure 1: Architecture layers

1.2.2. Class Hierarchy

To get a deeper understanding of the class hierarchy, the following class diagram seeks to abstract the classes and their hierarchical relationships:

Class diagram
Figure 2: Class diagram

1.2.3. Basic Types in SocioCortex

Shortly, we introduce the basic types that can be used within the SocioCortex ecosystem:

  • Number

  • String

  • Enumeration

  • Date

Furthermore, developers can define their own data types by creating respective entity type definitions as well as refine them with custom attribute definitions.

1.2.4. Helpful Resources

2. Configuration

2.1. Running your own SocioCortex server instance

If you want to run your own SocioCortex server, you’ll find instructions and all necessary files for an on-premise installation here.

As you will work with a different server domain as the sebis SocioCortex server, you need to adjust all the URIs in the Postman collection throughout this tutorial and replace server.sociocortex.com with your respective server url (e.g. if running the server locally localhost:8083).

2.2. Working with sebis SocioCortex server

If you want to work with the server instance provided by the sebis chair, you can do so by simply registering on https://server.sociocortex.com (see image below).

SocioCortex server
Figure 3: SocioCortex server

Alternatively, you can register over the REST-API itself as outlined in the upcoming section Authentication.

2.3. Postman setup

Postman is an application which is used to test and develop APIs. Its straightforward UI enables developers to send custom HTTP requests very comfortably. It can either be downloaded here: https://www.getpostman.com/

Or by simply clicking the button below:

3. Getting started with the REST-API

3.1. Introduction to demo scenario

The demo scenario that will serve as a real world example to demonstrate the usage of the SocioCortex REST-API is a simple publication management system.

Before we can start with the actual scenario, we check that the authentication is working for your credentials and shortly outline the differences of jwt and basic auth.

Once the authentication works, we create a workspace which we then use to store the required entity types in. We identify the required entity types as publication and conference. The latter we use to add entities, i.e. publications or conferences, to the workspace with respective entity types.

Furthermore, tasks and their definitions are introduced and combined with the attribute definitions of entity types.

While going through the demo scenario all HTTP verbs will be taken into account in order to make you feel comfortable with all kinds of actions necessary to interact with the SocioCortex REST-API.

3.1.1. Structure of resource URIs

Example URI for accessing all resources of type entityType within a workspace with a specific ID:

URI Schema
Figure 4: URI Schema

Additionally, one can provide query parameters to further refine for instance the requested meta attributes. More on query parameters can be found in [Query Parameters].

3.2. Authentication

In order to get started with SocioCortex, we first need to create an account to be able to create an own workspace as well as other entities.

3.2.1. Registering a new user (POST)

Request:

POST https://server.sociocortex.com/api/v1/users
BODY
{
    "name":"$NAME",
    "email":"$EMAIL@ADDRESS.com",
    "password":"$PASSWORD"
}

Response:

{
  "isVerified": false,
  "locale": "de-DE",
  "mayCreateWorkspace": false,
  "mayCreateGroup": false,
  "id": "$ID",
  "versions": [],
  "email": "$EMAIL@ADDRESS.com",
  "name": "$NAME",
  "href": "https://server.sociocortex.com/api/v1/users/$ID",
  "mayEdit": true,
  "isAdministrator": false,
  "mayCreateUser": false,
  "groups": []
}

After having successfully send this information to the server, we check the respective provided email account for an email containing an activation link for SocioCortex.

Activation email
Figure 5: Activation email

Once we click the link in the email, the account is activated and we are ready to go.

3.2.2. Log in to SocioCortex

There are two ways to log in to SocioCortex, either by HTTP Basic authentication or by using JSON Web Tokens (JWT, https://jwt.io/). Throughout this tutorial we will be using the predefined HTTP requests from the Postman-Collection. Therefore, we encourage you to simply replace the placeholder $TOKEN in all the Postman requests with your own JWT (see JWT).

Basic auth

Basic Auth requires to send a respective HTTP Authorization Header in every request to the server. This Authorization Header contains a username and password combined with a single colon and base64-encoded with a "Basic" prefix, denoting the authorization method. Thus, it does not require any cookies, session identifiers or tokens provided and signed by the server.

An example request to get a users details could be the following:

Request:

GET https://server.sociocortex.com/api/v1/users/me
Authorization: Basic $BASE64_ENCODED_CREDENTIALS
JWT

A JWT can be received by providing the credentials to the server in the payload of a HTTP POST request. The token has an expiry date in its payload as well as user information.

Request:

POST https://server.sociocortex.com/api/v1/jwt
BODY
{
    "username":"$EMAIL@ADDRESS.com",
    "password":"$PASSWORD"
}

Response:

{
  "token": "$TOKEN",
  "payload": {
    "exp": "$EXPIRY_DATE",
    "sub": "$USER_ID",
    "name": "$NAME"
  }
}

After having received the token, the token is sent with every request on access-restricted resources in a respective HTTP Authorization Header with the prefix "Bearer".

An example request to get a users details could be the following:

Request:

GET https://server.sociocortex.com/api/v1/users/me
Authorization: Bearer $TOKEN

3.3. Creating a workspace

Before creating our first workspace we check for the currently available workspaces because who knows, maybe someone else did the job for us already.

We do this with a simple HTTP GET request on the workspaces resource. The server will respond with a list of workspaces stored.

3.3.1. Looking for existing workspaces (GET)

Request:

GET https://server.sociocortex.com/api/v1/workspaces

Response:

[
  {
    "id": "944wcmiregxu",
    "name": "sc-visualizer",
    "href": "https://server.sociocortex.com/api/v1/workspaces/944wcmiregxu"
  },
  {
    "id": "107yhdgc7q9u6",
    "name": "Northwind",
    "href": "https://server.sociocortex.com/api/v1/workspaces/107yhdgc7q9u6"
  }
]

We can tell that no one has yet created a publication management workspace so we continue by creating one with a HTTP POST request.

3.3.2. Creating workspace publication management (POST)

Request:

POST https://server.sociocortex.com/api/v1/workspaces
BODY
{
    "name": "Publication Management"
}

Response:

{
  "id": "10sasph8dvxhg",
  "versions": ["..."],
  "rootEntity": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "mayCreateEntities": true,
  "isFavorite": false,
  "entityTree": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "name": "Publication Management",
  "permissions": {
    "contributors": [],
    "administrators": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "writers": [],
    "readers": []
  },
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
}

3.3.3. Looking at a single workspace (GET)

As we have seen in the response of the server on our POST request the workspace has been created with an id (in my case the id 10sasph8dvxhg). We can easily use this id now to get this specific workspace. In the following requests replace the id 10sasph8dvxhg with your own "$WORKSPACE_ID".

Request:

GET https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg

Response:

{
  "id": "10sasph8dvxhg",
  "versions": [
    {
      "action": "Edited",
      "date": "2016-07-15T17:06:42.012Z",
      "type": "_edit",
      "user": {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    },
    {
      "action": "Added",
      "date": "2016-07-15T17:06:41.371Z",
      "type": "_new",
      "user": {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    }
  ],
  "rootEntity": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "mayCreateEntities": true,
  "isFavorite": false,
  "entityTree": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "name": "Publication Management",
  "permissions": {
    "contributors": [],
    "administrators": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "writers": [],
    "readers": []
  },
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
}

There are some attributes which are obvious and some that will be introduced throughout the tutorial. In Permissions the concept of read/write accessibility is further discussed.

3.4. Creating entity types

Now that we have created the workspace where the publication management system will store its contents, we can continue by creating two entity types required to store publications prepared for and presented on multiple conferences.

3.4.1. Creating publication entity type (POST)

To create an entity type in a workspace we simply concat the URI of the workspace by /entityTypes and use the HTTP POST method to create a new entity type publication.

Request:

POST https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entityTypes
BODY
{
    "name": "Publication"
}

Response:

{
  "processes": [],
  "attributeDefinitions": [],
  "taskDefinitions": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "entitiesCount": 0,
  "structurednessMetric": 1,
  "id": "dt56spnul01p",
  "versions": [
    {
      "action": "Added",
      "date": "2016-07-15T17:26:37.202Z",
      "type": "_new",
      "user": {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    }
  ],
  "consistencyMetric": 1,
  "derivedAttributeDefinitions": [],
  "name": "Publication",
  "allowFreeAttributes": false,
  "associations": [],
  "incomingAssociations": [],
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
}

3.4.2. Creating conference entity type (POST)

Request:

POST https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entityTypes
BODY
{
    "name": "Conference"
}

Response:

{
  "processes": [],
  "attributeDefinitions": [],
  "taskDefinitions": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "entitiesCount": 0,
  "structurednessMetric": 1,
  "id": "19c48jgd4b8m2",
  "versions": [
    {
      "action": "Added",
      "date": "2016-07-15T17:29:20.655Z",
      "type": "_new",
      "user": {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    }
  ],
  "consistencyMetric": 1,
  "derivedAttributeDefinitions": [],
  "name": "Conference",
  "allowFreeAttributes": false,
  "associations": [],
  "incomingAssociations": [],
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
}

Finally, we have our workspace and the two required entity types set up. In the next steps we refine the attributes of the entity types before we start creating entities in the step after.

3.5. Creating attribute definitions

Sociocortex offers the possibility to create custom attribute definitions for attributes of entity types. This is a common task and you can make use of the attribute types introduced in Concepts or define relations between entity types.

3.5.1. Creating text attributes (POST)

The simplest attribute defintion type is surely a text attribute. We create a text attribute Abstract which should store the abstract of a publication. Therefore we send a HTTP POST request on the attribute definitions of the respective entity type - in this case the publication.

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/attributeDefinitions
BODY
{
    "name": "Abstract",
    "multiplicity": "maximalOne",
    "attributeType": "Text"
}

Response:

{
  "id": "2gegqgdueyqd",
  "versions": [],
  "readOnly": false,
  "name": "Abstract",
  "multiplicity": "maximalOne",
  "attributeType": "Text",
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/2gegqgdueyqd"
}

More attribute definitions of the various types are created in the next sections. For the matter of simplicity, we leave out the responses for the following requests.

3.5.2. Creating numeric attributes (POST)

Every conference needs a year in which it is taking place. We use a numeric attribute respectively:

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2/attributeDefinitions
BODY
{
    "name": "Year",
    "multiplicity": "maximalOne",
    "attributeType": "Number"
}

3.5.3. Creating enumeration attributes (POST)

Every publication needs one of the statuses: Planned, Submitted, Accepted. We will create an attribute defintion of type enum to realize this.

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/attributeDefinitions
BODY
{
    "name": "Status",
    "multiplicity": "maximalOne",
    "attributeType": "Enumeration",
    "options": {
        "enumerationValues": [
          "Planned",
          "Submitted",
          "Accepted"
        ]
    }
}

Conferences also require an enum attribute - the rank of the conference:

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2/attributeDefinitions
BODY
{
    "name": "Rank",
    "multiplicity": "maximalOne",
    "attributeType": "Enumeration",
    "options": {
        "enumerationValues": [
          "A",
          "B",
          "C"
        ]
    }
}

3.5.4. Creating relation attributes (POST)

A simple example for a relation among two entity types is an acceptedIn relation for publications. Once they are accepted by a conference the conferences are stored in this attribute.

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/attributeDefinitions
BODY
{
    "name": "acceptedIn",
    "multiplicity": "any",
    "attributeType": "Link",
    "options": {
        "entityType": {
          "id": "19c48jgd4b8m2"
        },
        "resourceType": "entities"
    }
}

Another straightforward relation is the mapping of authors to publications:

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/attributeDefinitions
BODY
{
    "name": "authors",
    "multiplicity": "any",
    "attributeType": "Link",
    "options": {
        "resourceType": "users"
    }
}

3.6. Creating entities

To create entities of the two entity types send HTTP POST requests to the types' endpoints, defined by their respective id.

3.6.1. Creating a conference entity (POST)

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2/entities
BODY
{
    "name": "International Conference on Software Engineering (ICSE)",
    "attributes":[
        {
            "name":"Rank",
            "values":["A"]
        },
        {
            "name":"Year",
            "values":[2016]
        }
    ]
}

Response:

{
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "tasks": [],
  "entityType": {
    "id": "19c48jgd4b8m2",
    "name": "Conference",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "n6eidlmr0by7",
  "versions": ["..."],
  "createdAt": "2016-07-24T11:12:00.000Z",
  "name": "International Conference on Software Engineering (ICSE)",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "pme5rnjsvx5z",
      "values": [
        "A"
      ],
      "name": "Rank",
      "href": "https://server.sociocortex.com/api/v1/attributes/pme5rnjsvx5z"
    },
    {
      "id": "voa7iqjet7pf",
      "values": [
        2016
      ],
      "name": "Year",
      "href": "https://server.sociocortex.com/api/v1/attributes/voa7iqjet7pf"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7",
  "lastModifiedAt": "2016-07-24T11:12:00.000Z"
}

3.6.2. Creating a publication entity (POST)

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/entities
BODY
{
    "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
    "attributes":[
        {
            "name":"acceptedIn",
            "values":[{"id":"n6eidlmr0by7"}]
        },
        {
            "name":"Abstract",
            "values": ["Today's enterprises have to align their information systems continuously with their dynamic business and IT environment. ..."]
        },
        {
            "name":"Status",
            "values":["Accepted"]
        },
        {
            "name":"authors",
            "values":[{
                "id":"1hda5st2csfom"
            }]
        }
    ]
}

Response:

{
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "tasks": [],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "127trtufzdgcw",
  "versions": ["..."],
  "createdAt": "2016-07-24T11:27:26.000Z",
  "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "7mgjht1rkna8",
      "values": [
        {
          "id": "1hda5st2csfom",
          "name": "Thomas Reschenhofer",
          "href": "https://server.sociocortex.com/api/v1/users/1hda5st2csfom"
        }
      ],
      "name": "authors",
      "href": "https://server.sociocortex.com/api/v1/attributes/7mgjht1rkna8"
    },
    {
      "id": "iqqlpxfbnr8f",
      "values": [
        {
          "id": "n6eidlmr0by7",
          "name": "International Conference on Software Engineering (ICSE)",
          "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7"
        }
      ],
      "name": "acceptedIn",
      "href": "https://server.sociocortex.com/api/v1/attributes/iqqlpxfbnr8f"
    },
    {
      "id": "rvzij9nn9of4",
      "values": [
        "Accepted"
      ],
      "name": "Status",
      "href": "https://server.sociocortex.com/api/v1/attributes/rvzij9nn9of4"
    },
    {
      "id": "ys69v6zjfz54",
      "values": [
        "Today's enterprises have to align their information systems continuously with their dynamic business and IT environment. ..."
      ],
      "name": "Abstract",
      "href": "https://server.sociocortex.com/api/v1/attributes/ys69v6zjfz54"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw",
  "lastModifiedAt": "2016-07-24T11:27:26.000Z"
}

3.7. Getting entity types

As we have created two entity types with respective instances, it might be interesting to query these types and their attribute definitions. The SocioCortex REST-API offers the possibility to further refine queries by query parameters, e.g. by specifying desired attributes or meta attributes. A more detailed description can be found in [Query Parameters].

3.7.1. Looking at all created entity types (GET)

Request:

GET https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entityTypes

Response:

[
  {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  {
    "id": "19c48jgd4b8m2",
    "name": "Conference",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
  }
]

If more specific information about these entity types is required, we simply add the query parameter meta with value * :

Request:

GET https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entityTypes?meta=*

Response:

[
  {
    "processes": [],
    "attributeDefinitions": [
      {
        "id": "2gegqgdueyqd",
        "versions": [],
        "readOnly": false,
        "name": "Abstract",
        "multiplicity": "maximalOne",
        "attributeType": "Text",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/2gegqgdueyqd"
      },
      {
        "id": "1knrlnoj7kjer",
        "versions": [],
        "readOnly": false,
        "name": "acceptedIn",
        "multiplicity": "any",
        "attributeType": "Link",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer",
        "options": {
          "entityType": {
            "id": "19c48jgd4b8m2",
            "name": "Conference",
            "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
          },
          "resourceType": "entities"
        }
      },
      {
        "id": "18b1hu00gnxdi",
        "versions": [],
        "readOnly": false,
        "name": "authors",
        "multiplicity": "any",
        "attributeType": "Link",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/18b1hu00gnxdi",
        "options": {
          "resourceType": "users"
        }
      },
      {
        "id": "mfpco2wx3zqp",
        "versions": [],
        "readOnly": false,
        "name": "Status",
        "multiplicity": "maximalOne",
        "attributeType": "Enumeration",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/mfpco2wx3zqp",
        "options": {
          "enumerationValues": [
            "Planned",
            "Submitted",
            "Accepted"
          ]
        }
      }
    ],
    "taskDefinitions": [],
    "workspace": {
      "id": "10sasph8dvxhg",
      "name": "Publication Management",
      "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
    },
    "entitiesCount": 6,
    "structurednessMetric": 1,
    "id": "dt56spnul01p",
    "versions": ["..."],
    "consistencyMetric": 1,
    "derivedAttributeDefinitions": [],
    "name": "Publication",
    "allowFreeAttributes": false,
    "associations": [
      {
        "id": "1knrlnoj7kjer",
        "versions": [],
        "readOnly": false,
        "name": "acceptedIn",
        "multiplicity": "any",
        "attributeType": "Link",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer",
        "options": {
          "entityType": {
            "id": "19c48jgd4b8m2",
            "name": "Conference",
            "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
          },
          "resourceType": "entities"
        }
      }
    ],
    "incomingAssociations": [],
    "customFunctions": [],
    "mayEdit": true,
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  {
    "processes": [],
    "attributeDefinitions": [
      {
        "id": "5ybnu95cmhfq",
        "versions": [],
        "readOnly": false,
        "name": "Rank",
        "multiplicity": "maximalOne",
        "attributeType": "Enumeration",
        "entityType": {
          "id": "19c48jgd4b8m2",
          "name": "Conference",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/5ybnu95cmhfq",
        "options": {
          "enumerationValues": [
            "A",
            "B",
            "C"
          ]
        }
      },
      {
        "id": "m4kghlbyf1e5",
        "versions": [],
        "readOnly": false,
        "name": "Year",
        "multiplicity": "maximalOne",
        "attributeType": "Number",
        "entityType": {
          "id": "19c48jgd4b8m2",
          "name": "Conference",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/m4kghlbyf1e5"
      }
    ],
    "taskDefinitions": [],
    "workspace": {
      "id": "10sasph8dvxhg",
      "name": "Publication Management",
      "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
    },
    "entitiesCount": 5,
    "structurednessMetric": 1,
    "id": "19c48jgd4b8m2",
    "versions": ["..."],
    "consistencyMetric": 1,
    "derivedAttributeDefinitions": [],
    "name": "Conference",
    "allowFreeAttributes": false,
    "associations": [],
    "incomingAssociations": [
      {
        "id": "1knrlnoj7kjer",
        "versions": [],
        "readOnly": false,
        "name": "acceptedIn",
        "multiplicity": "any",
        "attributeType": "Link",
        "entityType": {
          "id": "dt56spnul01p",
          "name": "Publication",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
        },
        "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer",
        "options": {
          "entityType": {
            "id": "19c48jgd4b8m2",
            "name": "Conference",
            "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
          },
          "resourceType": "entities"
        }
      }
    ],
    "customFunctions": [],
    "mayEdit": true,
    "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
  }
]

3.7.2. Looking at the publication entity type (GET)

To retrieve details about a single entity we add the respective id to the URI.

Request:

GET https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p

Response:

{
  "processes": [],
  "attributeDefinitions": [
    {
      "id": "2gegqgdueyqd",
      "versions": [],
      "readOnly": false,
      "name": "Abstract",
      "multiplicity": "maximalOne",
      "attributeType": "Text",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/2gegqgdueyqd"
    },
    {
      "id": "1knrlnoj7kjer",
      "versions": [],
      "readOnly": false,
      "name": "acceptedIn",
      "multiplicity": "any",
      "attributeType": "Link",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer",
      "options": {
        "entityType": {
          "id": "19c48jgd4b8m2",
          "name": "Conference",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
        },
        "resourceType": "entities"
      }
    },
    {
      "id": "18b1hu00gnxdi",
      "versions": [],
      "readOnly": false,
      "name": "authors",
      "multiplicity": "any",
      "attributeType": "Link",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/18b1hu00gnxdi",
      "options": {
        "resourceType": "users"
      }
    },
    {
      "id": "mfpco2wx3zqp",
      "versions": [],
      "readOnly": false,
      "name": "Status",
      "multiplicity": "maximalOne",
      "attributeType": "Enumeration",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/mfpco2wx3zqp",
      "options": {
        "enumerationValues": [
          "Planned",
          "Submitted",
          "Accepted"
        ]
      }
    }
  ],
  "taskDefinitions": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "entitiesCount": 6,
  "structurednessMetric": 1,
  "id": "dt56spnul01p",
  "versions": ["..."],
  "consistencyMetric": 1,
  "derivedAttributeDefinitions": [],
  "name": "Publication",
  "allowFreeAttributes": false,
  "associations": [
    {
      "id": "1knrlnoj7kjer",
      "versions": [],
      "readOnly": false,
      "name": "acceptedIn",
      "multiplicity": "any",
      "attributeType": "Link",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer",
      "options": {
        "entityType": {
          "id": "19c48jgd4b8m2",
          "name": "Conference",
          "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
        },
        "resourceType": "entities"
      }
    }
  ],
  "incomingAssociations": [],
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
}

3.8. Getting attribute definitions

3.8.1. Looking at attribute definitions of entity type (GET)

For our entity types we have created custom attribute definitions which might also be useful to have another look at. To query these we add the attributeDefinitions keyword:

Request:

GET https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/attributeDefinitions

Response:

[
  {
    "id": "2gegqgdueyqd",
    "name": "Abstract",
    "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/2gegqgdueyqd"
  },
  {
    "id": "1knrlnoj7kjer",
    "name": "acceptedIn",
    "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/1knrlnoj7kjer"
  },
  {
    "id": "18b1hu00gnxdi",
    "name": "authors",
    "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/18b1hu00gnxdi"
  },
  {
    "id": "mfpco2wx3zqp",
    "name": "Status",
    "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/mfpco2wx3zqp"
  }
]

3.9. Getting entities

Obviously, one of the most common tasks is to retrieve all the entities in a workspace or of a certain type. This can either be done by specifically searching for entities through the search endpoint (see Searching) or by querying by entity type, workspace or id of a single entity.

3.9.1. Looking at all existing entities in workspace (GET)

Request:

GET https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entities

Response:

[{
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  {
    "id": "n6eidlmr0by7",
    "name": "International Conference on Software Engineering (ICSE)",
    "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7"
  },
  {
    "id": "127trtufzdgcw",
    "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
    "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw"
}]

3.9.2. Looking at all existing entities of entity type publication (GET)

Request:

GET https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/entities

Response:

[{
    "id": "127trtufzdgcw",
    "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
    "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw"
}]

3.9.3. Looking at single entity (GET)

Request:

GET https://server.sociocortex.com/api/v1/entities/127trtufzdgcw

Response:

{
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "tasks": [],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "127trtufzdgcw",
  "versions": ["..."],
  "createdAt": "2016-07-24T11:27:26.000Z",
  "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "7mgjht1rkna8",
      "values": [
        {
          "id": "1hda5st2csfom",
          "name": "Thomas Reschenhofer",
          "href": "https://server.sociocortex.com/api/v1/users/1hda5st2csfom"
        }
      ],
      "name": "authors",
      "href": "https://server.sociocortex.com/api/v1/attributes/7mgjht1rkna8"
    },
    {
      "id": "iqqlpxfbnr8f",
      "values": [
        {
          "id": "n6eidlmr0by7",
          "name": "International Conference on Software Engineering (ICSE)",
          "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7"
        }
      ],
      "name": "acceptedIn",
      "href": "https://server.sociocortex.com/api/v1/attributes/iqqlpxfbnr8f"
    },
    {
      "id": "rvzij9nn9of4",
      "values": [
        "Accepted"
      ],
      "name": "Status",
      "href": "https://server.sociocortex.com/api/v1/attributes/rvzij9nn9of4"
    },
    {
      "id": "ys69v6zjfz54",
      "values": [
        "Today's enterprises have to align their information systems continuously with their dynamic business and IT environment. ..."
      ],
      "name": "Abstract",
      "href": "https://server.sociocortex.com/api/v1/attributes/ys69v6zjfz54"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw",
  "lastModifiedAt": "2016-07-24T11:27:26.000Z"
}

3.10. Tasks and task definitions

Attributes of entity types can be linked to tasks, which means that for instance a task is not yet completed until a certain attribute it is linked to is set. Task definitions create those links between attributes and tasks to be fulfilled. In the following, we will first create a task definition for the previously defined status attribute of the publication entity type. Then, we create a new publication entity whose status is not set to any value yet. Last, the status of new entity is updated and set to accepted. This will fulfill the respective task.

3.10.1. Create task definition (POST)

For creating the task definition, we require the id of the previously defined entity type publication as well as the id of the attribute definition of Status which it contains. You need to replace them with your own values in order to make the requests work.

Request:

POST https://server.sociocortex.com/api/v1/taskDefinitions
BODY
{
  "name": "Publication Status",
  "entityType": {
    "id":"dt56spnul01p"
  },
  "attributeDefinitions": [
    {
      "id":"mfpco2wx3zqp"
    }
  ]
}

Response:

{
  "attributeDefinitions": [
    {
      "id": "mfpco2wx3zqp",
      "versions": [],
      "readOnly": false,
      "name": "Status",
      "multiplicity": "maximalOne",
      "attributeType": "Enumeration",
      "entityType": {
        "id": "dt56spnul01p",
        "name": "Publication",
        "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
      },
      "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/mfpco2wx3zqp",
      "options": {
        "enumerationValues": [
          "Planned",
          "Submitted",
          "Accepted"
        ]
      }
    }
  ],
  "id": "875jp376lljp",
  "satisfies": [],
  "name": "Publication Status",
  "tasks": [],
  "preconditions": [],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "href": "https://server.sociocortex.com/api/v1/taskDefinitions/875jp376lljp"
}

3.10.2. Create entity publication (POST)

Next, we create a new publication where we purposefully do not set all the defined attributes yet.

Request:

POST https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p/entities
BODY
{
    "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
    "attributes":[
        {
            "name":"acceptedIn",
            "values":[]
        },
        {
            "name":"Abstract",
            "values": ["Knowledge work is becoming the predominant type of work in many countries and is involved in the most important processes in organizations. ..."]
        },
        {
            "name":"Status",
            "values":[]
        },
        {
            "name":"authors",
            "values":[]
        }
    ]
}

Response:

{
  "isOverdue": false,
  "progress": 0,
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "isInconsistent": false,
  "tasks": [
    {
      "expertises": [],
      "isOverdue": false,
      "progress": 0,
      "id": "1jxlh7fiinyp3",
      "taskDefinition": {
        "id": "875jp376lljp",
        "name": "Publication Status",
        "href": "https://server.sociocortex.com/api/v1/taskDefinitions/875jp376lljp"
      },
      "skipped": false,
      "isProgressCalculated": true,
      "entity": {
        "id": "pvv5b7tg2ave",
        "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
        "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave"
      },
      "name": "Publication Status",
      "attributes": [
        {
          "id": "1nnq4l3r7xiez",
          "name": "Status",
          "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
        }
      ],
      "isInconsistent": false,
      "href": "https://server.sociocortex.com/api/v1/tasks/1jxlh7fiinyp3"
    }
  ],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "pvv5b7tg2ave",
  "versions": ["..."],
  "createdAt": "2016-07-25T12:12:42.000Z",
  "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "1fxaj2nfs3yp9",
      "values": [],
      "name": "authors",
      "href": "https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9"
    },
    {
      "id": "1nnq4l3r7xiez",
      "values": [],
      "name": "Status",
      "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
    },
    {
      "id": "1r36ijukwwbtf",
      "values": [],
      "name": "acceptedIn",
      "href": "https://server.sociocortex.com/api/v1/attributes/1r36ijukwwbtf"
    },
    {
      "id": "1rc9u2if7o62m",
      "values": [
        "Knowledge work is becoming the predominant type of work in many countries and is involved in the most important processes in organizations. ..."
      ],
      "name": "Abstract",
      "href": "https://server.sociocortex.com/api/v1/attributes/1rc9u2if7o62m"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave",
  "lastModifiedAt": "2016-07-25T12:12:42.000Z"
}

3.10.3. Updating status of publication (PUT)

If we look at the entity we just created, we can see a task list being attached to it with one open task concerning the taskDefinition we created before. Its progress is 0 and thus the task is not yet fulfilled.

Request:

GET https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave

Response:

{
  "isOverdue": false,
  "progress": 0,
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "isInconsistent": false,
  "tasks": [
    {
      "expertises": [],
      "isOverdue": false,
      "progress": 0,
      "id": "1jxlh7fiinyp3",
      "taskDefinition": {
        "id": "875jp376lljp",
        "name": "Publication Status",
        "href": "https://server.sociocortex.com/api/v1/taskDefinitions/875jp376lljp"
      },
      "skipped": false,
      "isProgressCalculated": true,
      "entity": {
        "id": "pvv5b7tg2ave",
        "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
        "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave"
      },
      "name": "Publication Status",
      "attributes": [
        {
          "id": "1nnq4l3r7xiez",
          "name": "Status",
          "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
        }
      ],
      "isInconsistent": false,
      "href": "https://server.sociocortex.com/api/v1/tasks/1jxlh7fiinyp3"
    }
  ],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "pvv5b7tg2ave",
  "versions": ["..."],
  "createdAt": "2016-07-25T12:12:42.000Z",
  "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "1fxaj2nfs3yp9",
      "values": [],
      "name": "authors",
      "href": "https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9"
    },
    {
      "id": "1nnq4l3r7xiez",
      "values": [],
      "name": "Status",
      "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
    },
    {
      "id": "1r36ijukwwbtf",
      "values": [],
      "name": "acceptedIn",
      "href": "https://server.sociocortex.com/api/v1/attributes/1r36ijukwwbtf"
    },
    {
      "id": "1rc9u2if7o62m",
      "values": [
        "Knowledge work is becoming the predominant type of work in many countries and is involved in the most important processes in organizations. ..."
      ],
      "name": "Abstract",
      "href": "https://server.sociocortex.com/api/v1/attributes/1rc9u2if7o62m"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave",
  "lastModifiedAt": "2016-07-25T12:12:42.000Z"
}

In order to fulfill the task we update the concurrent entity by using the HTTP PUT method to change the status to Accepted. The response contains the updated entity with a progress of the task of 100 which means it is fulfilled.

Request:

PUT https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave
BODY
{
    "attributes":[
        {
            "id": "1nnq4l3r7xiez",
            "name":"Status",
            "values": ["Accepted"]
        }
    ]
}

Response:

{
  "isOverdue": false,
  "progress": 100,
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "isInconsistent": false,
  "tasks": [
    {
      "progress": 100,
      "isOverdue": false,
      "taskDefinition": {
        "id": "875jp376lljp",
        "name": "Publication Status",
        "href": "https://server.sociocortex.com/api/v1/taskDefinitions/875jp376lljp"
      },
      "entity": {
        "id": "pvv5b7tg2ave",
        "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
        "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave"
      },
      "isProgressCalculated": true,
      "isInconsistent": false,
      "expertises": [],
      "id": "1jxlh7fiinyp3",
      "skipped": false,
      "name": "Publication Status",
      "finishedAt": "2016-07-26T07:22:35.000Z",
      "finishedBy": {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      },
      "attributes": [
        {
          "id": "1nnq4l3r7xiez",
          "name": "Status",
          "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
        }
      ],
      "href": "https://server.sociocortex.com/api/v1/tasks/1jxlh7fiinyp3"
    }
  ],
  "entityType": {
    "id": "dt56spnul01p",
    "name": "Publication",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
  },
  "incomingReferences": {},
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "pvv5b7tg2ave",
  "versions": ["..."],
  "createdAt": "2016-07-25T12:12:42.000Z",
  "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "1fxaj2nfs3yp9",
      "values": [],
      "name": "authors",
      "href": "https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9"
    },
    {
      "id": "1nnq4l3r7xiez",
      "values": [
        "Accepted"
      ],
      "name": "Status",
      "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
    },
    {
      "id": "1r36ijukwwbtf",
      "values": [],
      "name": "acceptedIn",
      "href": "https://server.sociocortex.com/api/v1/attributes/1r36ijukwwbtf"
    },
    {
      "id": "1rc9u2if7o62m",
      "values": [
        "Knowledge work is becoming the predominant type of work in many countries and is involved in the most important processes in organizations. ..."
      ],
      "name": "Abstract",
      "href": "https://server.sociocortex.com/api/v1/attributes/1rc9u2if7o62m"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave",
  "lastModifiedAt": "2016-07-25T12:12:42.000Z"
}

3.11. Updating entities and entity types

3.11.1. Updating name of entity (PUT)

The easiest way to demonstrate how entities are updated is by sending a HTTP PUT request on an existing conference which is supposed to change the name of the conference. Let’s assume we just want to get rid of the abbreviation of the conference (ICSE).

Request:

PUT https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7
{
    "name":"International Conference on Software Engineering"
}

Response:

{
  "files": [],
  "workspace": {
    "id": "10sasph8dvxhg",
    "name": "Publication Management",
    "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
  },
  "children": [],
  "tasks": [],
  "entityType": {
    "id": "19c48jgd4b8m2",
    "name": "Conference",
    "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2"
  },
  "incomingReferences": {
    "acceptedIn": [
      {
        "id": "127trtufzdgcw",
        "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
        "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw"
      }
    ]
  },
  "creator": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "id": "n6eidlmr0by7",
  "versions": ["..."],
  "createdAt": "2016-07-24T11:12:00.000Z",
  "name": "International Conference on Software Engineering",
  "lastModifier": {
    "id": "$USER_ID",
    "name": "$NAME",
    "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
  },
  "permissions": {
    "writers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "readers": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ]
  },
  "attributes": [
    {
      "id": "pme5rnjsvx5z",
      "values": [
        "A"
      ],
      "name": "Rank",
      "href": "https://server.sociocortex.com/api/v1/attributes/pme5rnjsvx5z"
    },
    {
      "id": "voa7iqjet7pf",
      "values": [
        2016
      ],
      "name": "Year",
      "href": "https://server.sociocortex.com/api/v1/attributes/voa7iqjet7pf"
    }
  ],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7",
  "lastModifiedAt": "2016-07-24T18:18:06.000Z"
}

3.11.2. Updating single attribute of entity (PUT)

As attributes might change over time, it might be necessary to change an attribute of an entity at some point. This can be done by sending a HTTP PUT request to a certain attribute identified by its id. The latter can be found out by querying the respective entity first (see Looking at single entity (GET)). Let’s assume we want to change the authors of the publication created in Create entity publication (POST) where in our case the id of the authors attribute is 1fxaj2nfs3yp9.

Request:

PUT https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9
BODY
{
    "values":[{
        "id":"1d94htksgwy2i",
        "name": "Matheus Hauder"
    }]
}

Response:

{
  "id": "1fxaj2nfs3yp9",
  "values": [
    {
      "id": "1d94htksgwy2i",
      "name": "Matheus Hauder",
      "href": "https://server.sociocortex.com/api/v1/users/1d94htksgwy2i"
    }
  ],
  "attributeDefinition": {
    "id": "18b1hu00gnxdi",
    "versions": [],
    "readOnly": false,
    "name": "authors",
    "multiplicity": "any",
    "attributeType": "Link",
    "entityType": {
      "id": "dt56spnul01p",
      "name": "Publication",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p"
    },
    "href": "https://server.sociocortex.com/api/v1/attributeDefinitions/18b1hu00gnxdi",
    "options": {
      "resourceType": "users"
    }
  },
  "name": "authors",
  "href": "https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9"
}

3.12. Deleting instances

Deletion is generally not different to any of the other considered action except for the HTTP verb. For deleting instances (e.g. entities, entityTypes or workspaces), one can simply send the HTTP DELETE verb to a respective resource endpoint (i.e. URI). However, it is recommended to get first get an understanding of how SocioCortex handles deletion and what cascading deletion behavior one has to expect.

An example for deleting the previously created workspace publication management is the following:

Request:

DELETE https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg

If deleting instances is important for you, there is a master thesis covering the deletion behavior more detailed, it can be downloaded here (see slide 9).

4. Permissions

In Getting started with the REST-API the permissions were shortly mentioned. In this section the underlying concept of accessibility is explained more precisely. There are three types of accessibility rights: read, edit and contribute permissions. Editors can read and edit pages and their attachments. In addition to editors, readers have read-only access to pages which do not override this setting. Contributors are allowed to create new pages in respective workspaces. They may only read/edit pages to which they are explicitly assigned as readers/editors. Accessibility rules can be inherited from the containing workspace or from parent entities. By default, newly created entities will inherit readers and editors from their workspace.

In order to change the permissions to workspaces or certain entities, the REST-API or the server user interface (https://server.sociocortex.com) can be used:

Set permissions of entity via UI
Figure 6: Set permissions of entity via UI
Set permissions of workspace via UI
Figure 7: Set permissions of workspace via UI

4.1. Add reader to workspace

For the SocioCortex REST-API, we take the workspace created in Creating a workspace and add another reader to the workspace. In our case this is a user with the id aosqsp1qsrfa which we simply add to the array of readers in the permissions object.

Request:

PUT https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg
BODY
{
    "permissions": {
        "readers": [{
            "id": "aosqsp1qsrfa"
        }]
    }
}

Response:

{
  "id": "10sasph8dvxhg",
  "versions": ["..."],
  "rootEntity": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "mayCreateEntities": true,
  "isFavorite": false,
  "entityTree": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "name": "Publication Management",
  "permissions": {
    "contributors": [],
    "administrators": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "writers": [],
    "readers": [
      {
        "id": "aosqsp1qsrfa",
        "name": "daniel",
        "href": "https://server.sociocortex.com/api/v1/users/aosqsp1qsrfa"
      }
    ]
  },
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
}

4.2. Add editor to workspace

Request:

PUT https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg
BODY
{
    "permissions": {
        "writers": [{
            "id": "aosqsp1qsrfa"
        }]
    }
}

Response:

{
  "id": "10sasph8dvxhg",
  "versions": ["..."],
  "rootEntity": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "mayCreateEntities": true,
  "isFavorite": false,
  "entityTree": {
    "id": "bqr7jmg37vqt",
    "name": "Publication Management - Home",
    "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt"
  },
  "name": "Publication Management",
  "permissions": {
    "contributors": [],
    "administrators": [
      {
        "id": "$USER_ID",
        "name": "$NAME",
        "href": "https://server.sociocortex.com/api/v1/users/$USER_ID"
      }
    ],
    "writers": [
      {
        "id": "aosqsp1qsrfa",
        "name": "daniel",
        "href": "https://server.sociocortex.com/api/v1/users/aosqsp1qsrfa"
      }
    ],
    "readers": [
      {
        "id": "aosqsp1qsrfa",
        "name": "daniel",
        "href": "https://server.sociocortex.com/api/v1/users/aosqsp1qsrfa"
      }
    ]
  },
  "customFunctions": [],
  "mayEdit": true,
  "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg"
}

5. Optional request parameters

When looking at the responses from the server you might have noticed that some returned entities or workspaces contain more attributes/information than others. The reason for that is that by default when returning a list, the SocioCortex REST-API includes only certain attributes in the returned objects. Thus, when getting all workspaces in Creating a workspace the list of results only contained the attributes id,name and href. However, the response for a single workspace contained attributes such as permissions, versions or rootEntity. The same applies to entities which we queried in Getting entities. Here, by querying single entities the self-defined attributes were included which we did not see when getting a list of entities. Now, when querying a list one might also be interested in certain attributes which are not by default included in the responded list, e.g. attributes you defined yourself. The SocioCortex REST-API enables developers to do so by adding request parameters which are introduced in the following subsections.

5.1. Meta

As mentioned above when getting all workspaces the responses are missing so-called meta attributes as permissions. They are meta attributes as they are generated for every workspace or entity that is created in SocioCortex. By appending the meta request parameter these can be manually included. Basically, you can either append a comma-separated list of attributes that are supposed to be included or simply add a * to include all attributes.

Examples:

https://server.sociocortex.com/api/v1/workspaces?meta=permissions

Returns all workspaces and includes the permissions meta attribute.

https://server.sociocortex.com/api/v1/workspaces?meta=*

Returns all workspaces and includes all meta attributes.

5.2. Attributes

In order to include certain attributes (e.g. self-defined attributes) in the responded list of entities, the request parameter attributes is appended to the URI (see URI schema in Introduction to demo scenario). As for meta attributes, you either include a * for all attributes or a comma-separated list of attributes.

Examples:

https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entities?attributes=Year,Rank

Returns all entities of a workspace and includes the self-defined attributes Year and Rank.

https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entities?attributes=*

Returns all entities of a workspace and includes all attributes of entity types.

5.3. Content

When querying entities one might be willing to include or exclude the content of certain entities such as text pages. Therefore, the content parameter enables us to simply set a flag whether the rich-text content of the entity should be included in the response.

Example:

https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entities?content=true

Returns all entities of a workspace and includes their rich-text content.

5.4. Tasks

Tasks are linked to attributes as we have seen in Tasks and task definitions. When retrieving entities from a server developers can add a boolean parameter tasks to the URI indicating if the tasks of the entity should be included in the response.

Example:

https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg/entities?tasks=true

Returns all entities of a workspace and includes their respective linked tasks.

6. Searching

There are two endpoints in the SocioCortex REST-API which offer the ability to search for instances of all types of classes that SocioCortex consists of: * Search hints: Retrieves a list of search hints containing basic information and a disambiguation of search hits. * Search results: Retrieves a list of search hints containing full information, e.g., attributes of entities, meta information, and highlighted search hits.

Both options allow developers to search by text, workspace, entityType or resource type. Additionally, the search results may also include all query parameters listed in [Query Parameters], e.g. (meta) attributes, and thus could contain the entire entity objects. The search hints are a limited data sample which can be helpful when implementing an autocompletion search or other use cases where the data samples to not necessarily have to contain all relevant attributes/information.

Moreover, search hints and results can be ordered by attributes in two directions (ascending, descending) and limited by number. For performance reasons for the search results endpoint a server-side pagination is also provided.

For a complete list of filter parameters have a look at the REST-API specification which can be found here.

6.1. Search hints

6.1.1. Searching for all instances in workspace

Let’s start by requesting all instances of classes in the workspace publication management.

Request:

GET https://server.sociocortex.com/api/v1/searchHints?workspace=10sasph8dvxhg

Response:

{
  "totalCount": 8,
  "hints": [
    {
      "id": "dt56spnul01p",
      "disambiguation": "Publication Management",
      "name": "Publication",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p",
      "resourceType": "entityTypes"
    },
    {
      "id": "1bbxmsluu87f7",
      "disambiguation": "Publication Management",
      "name": "Text Page",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/1bbxmsluu87f7",
      "resourceType": "entityTypes"
    },
    {
      "id": "19c48jgd4b8m2",
      "disambiguation": "Publication Management",
      "name": "Conference",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2",
      "resourceType": "entityTypes"
    },
    {
      "id": "127trtufzdgcw",
      "disambiguation": "/Publication Management/_",
      "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
      "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw",
      "resourceType": "entities"
    },
    {
      "id": "10sasph8dvxhg",
      "name": "Publication Management",
      "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg",
      "resourceType": "workspaces"
    },
    {
      "id": "pvv5b7tg2ave",
      "disambiguation": "/Publication Management/_",
      "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
      "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave",
      "resourceType": "entities"
    },
    {
      "id": "n6eidlmr0by7",
      "disambiguation": "/Publication Management/_",
      "name": "International Conference on Software Engineering",
      "href": "https://server.sociocortex.com/api/v1/entities/n6eidlmr0by7",
      "resourceType": "entities"
    },
    {
      "id": "bqr7jmg37vqt",
      "disambiguation": "Publication Management",
      "name": "Publication Management - Home",
      "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt",
      "resourceType": "entities"
    }
  ]
}

The response contains an object which tells us the total count of results for these search parameters and lists all results with their respective resourceType.

6.1.2. Searching for text in all instances in workspace

To further specify what is searched for, the text query parameter can be appended to make a full-text search.

Request:

GET https://server.sociocortex.com/api/v1/searchHints?workspace=10sasph8dvxhg&text=Information

Response:

{
  "totalCount": 1,
  "hints": [
    {
      "id": "127trtufzdgcw",
      "disambiguation": "/Publication Management/_",
      "name": "Re16a - Lessons Learned in Aligning Data and Model Evolution in Collaborative Information Systems",
      "href": "https://server.sociocortex.com/api/v1/entities/127trtufzdgcw",
      "resourceType": "entities"
    }
  ]
}

6.1.3. Searching instances of resource type in workspace

Sometimes it might be necessary to search for instances of a certain resource type.

Request:

GET https://server.sociocortex.com/api/v1/searchHints?workspace=10sasph8dvxhg&resourceType=entityTypes

Response:

{
  "totalCount": 3,
  "hints": [
    {
      "id": "dt56spnul01p",
      "disambiguation": "Publication Management",
      "name": "Publication",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p",
      "resourceType": "entityTypes"
    },
    {
      "id": "1bbxmsluu87f7",
      "disambiguation": "Publication Management",
      "name": "Text Page",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/1bbxmsluu87f7",
      "resourceType": "entityTypes"
    },
    {
      "id": "19c48jgd4b8m2",
      "disambiguation": "Publication Management",
      "name": "Conference",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2",
      "resourceType": "entityTypes"
    }
  ]
}

6.2. Search results

Besides the search hints functionality, the search results endpoint also offers the ability to append query parameters to refine custom attribute inclusion (for query parameters see [Query Parameters]). As a result returned instances could contain all (meta) attributes or even the entire object with all attributes, tasks or relations. Consequently, the returned list needs to be limited in size to assure performance. The response object therefore contains a count of the total amount of results, but the result list only contains a max size of n results per page. These parameters can be manually set. For example if I want to retrieve 20 results per page and get the results of page 2 the following URI is to be requested:

GET https://server.sociocortex.com/api/v1/searchResults?workspace=10sasph8dvxhg&page=2&n=20

6.2.1. Searching for entities in a workspace (GET)

Request:

GET https://server.sociocortex.com/api/v1/searchResults?workspace=10sasph8dvxhg

Response:

{
  "results": [
    {
      "id": "dt56spnul01p",
      "name": "Publication",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/dt56spnul01p",
      "resourceType": "entityTypes"
    },
    {
      "id": "1bbxmsluu87f7",
      "name": "Text Page",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/1bbxmsluu87f7",
      "resourceType": "entityTypes"
    },
    {
      "id": "bqr7jmg37vqt",
      "name": "Publication Management - Home",
      "href": "https://server.sociocortex.com/api/v1/entities/bqr7jmg37vqt",
      "resourceType": "entities"
    },
    {
      "id": "10sasph8dvxhg",
      "name": "Publication Management",
      "href": "https://server.sociocortex.com/api/v1/workspaces/10sasph8dvxhg",
      "resourceType": "workspaces"
    },
    {
      "id": "19c48jgd4b8m2",
      "name": "Conference",
      "href": "https://server.sociocortex.com/api/v1/entityTypes/19c48jgd4b8m2",
      "resourceType": "entityTypes"
    },
    {
      "id": "15qr31m7ewuje",
      "name": "A sample paper",
      "href": "https://server.sociocortex.com/api/v1/entities/15qr31m7ewuje",
      "resourceType": "entities"
    },
    {
      "id": "24ixbhft7i4b",
      "name": "A sample conference",
      "href": "https://server.sociocortex.com/api/v1/entities/24ixbhft7i4b",
      "resourceType": "entities"
    }
  ],
  "totalCount": 7
}

6.2.2. Searching for entities with all attributes

To include all attributes in the result list the attributes parameter is appended to the search request URI. This request puts it all together, workspace, resourceType, orderBy and attribute filter.

Request:

GET https://server.sociocortex.com/api/v1/searchResults?text=Collaboratively&workspace=10sasph8dvxhg&resourceType=entities&orderBy=alphabetically&attributes=*

Response:

{
  "results": [
    {
      "isOverdue": false,
      "progress": 100,
      "id": "pvv5b7tg2ave",
      "highlightedName": "Ha15a - Empowering End-Users to <span class=\"sc-search-highlight\">Collaboratively</span> Structure Processes for Knowledge Work",
      "name": "Ha15a - Empowering End-Users to Collaboratively Structure Processes for Knowledge Work",
      "isInconsistent": false,
      "attributes": [
        {
          "id": "1fxaj2nfs3yp9",
          "values": [
            {
              "id": "1d94htksgwy2i",
              "name": "Matheus Hauder",
              "href": "https://server.sociocortex.com/api/v1/users/1d94htksgwy2i"
            }
          ],
          "name": "authors",
          "href": "https://server.sociocortex.com/api/v1/attributes/1fxaj2nfs3yp9"
        },
        {
          "id": "1nnq4l3r7xiez",
          "values": [
            "Accepted"
          ],
          "name": "Status",
          "href": "https://server.sociocortex.com/api/v1/attributes/1nnq4l3r7xiez"
        },
        {
          "id": "1r36ijukwwbtf",
          "values": [],
          "name": "acceptedIn",
          "href": "https://server.sociocortex.com/api/v1/attributes/1r36ijukwwbtf"
        },
        {
          "id": "1rc9u2if7o62m",
          "values": [
            "Knowledge work is becoming the predominant type of work in many countries and is involved in the most important processes in organizations. ..."
          ],
          "name": "Abstract",
          "href": "https://server.sociocortex.com/api/v1/attributes/1rc9u2if7o62m"
        }
      ],
      "href": "https://server.sociocortex.com/api/v1/entities/pvv5b7tg2ave",
      "resourceType": "entities"
    }
  ],
  "totalCount": 1
}