Create entities and relationships

Showing JavaScript examples.

This guide shows you how to create DataSync objects: entities, relationships, users, channels, and memberships. All creates require a valid Access Manager token. Refer to Grant DataSync access if you don't have a token yet.

Before you start

• DataSync must be enabled on your keyset. Refer to Enable DataSync.
• The class you're creating an instance of must exist on the keyset. Refer to Define an entity class.
• Access Manager must be enabled and your client must have a token with create permission on the target resource type.

Create an entity

Supply the class name, the class version, and optionally an id, a status, and a payload.

• JavaScript
• C#

1const response = await pubnub.dataSync.createEntity({
2    id: 'product-sneaker-42',
3    class: 'Product',
4    data: {
5        classVersion: 1,
6        payload: { name: 'Retro Sneaker', price: 89.99, stock: 12 },
7    },
8})

Using the REST API directly:

1curl -X POST 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities?auth=<token>&uuid=catalog-service' \
2  -H 'Content-Type: application/vnd.pubnub.objects.entity+json;version=1' \
3  -d '{
4    "data": {
5      "id": "product-sneaker-42",
6      "entityClass": "Product",
7      "entityClassVersion": 1,
8      "payload": { "name": "Retro Sneaker", "price": 89.99, "stock": 12 }
9    }
10  }'

Set uuid to the user ID the token was granted to, catalog-service in this example. If uuid doesn't match the token's authorized user ID, Access Manager rejects the request with a 403. The SDKs send uuid for you.

If you omit id, the server generates a UUID for you. If you supply an id that already exists, the request is rejected with a 409 Conflict.

Refer to Create entity (JavaScript), Create entity (C#), and Create entity (REST) for the full parameter reference.

Create a user

A user requires only the class version. The class name defaults to User. This example uses MarketplaceUser, the subclass from Extend a Global class.

• JavaScript
• C#

1const created = await pubnub.dataSync.createUser({
2    id: 'user-alice',
3    class: 'MarketplaceUser',
4    data: {
5        classVersion: 1,
6        payload: {
7            name: 'Alice',
8            type: 'shopper',
9            display_name: 'Alice',
10        },
11    },
12})

The payload leaves out email on purpose. email belongs only to the admin projection, and a client token without that projection can't write it. The request fails with a 403 and error code DS-0202. Set admin-only fields from your server. Refer to Projections.

Refer to Create user (JavaScript), Create user (C#), and Create user (REST) for the full parameter reference.

Create a channel

A channel requires only the class version. The class name defaults to Channel.

• JavaScript
• C#

1const channel = await pubnub.dataSync.createChannel({
2    id: 'channel-summer-sale',
3    data: {
4        classVersion: 1,
5        payload: { name: 'Summer Sale', type: 'promotion' },
6    },
7})

Refer to Create channel (REST) for the request and response reference.

A channel entity is not a pub/sub channel

Creating a channel entity doesn't create or configure the underlying Pub/Sub channel. The entity holds metadata. Messaging works whether or not the entity exists. Refer to Built-in types.

Create a membership

A membership requires channelId, userId, and relationshipClassVersion. Both the channel and the user must already exist.

• JavaScript
• C#

1const membership = await pubnub.dataSync.createMembership({
2    id: 'membership-alice-summer-sale',
3    userId: 'user-alice',
4    channelId: 'channel-summer-sale',
5    data: {
6        classVersion: 1,
7        payload: { role: 'viewer' },
8    },
9})

Using the REST API directly:

1curl -X POST 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/memberships?auth=<token>&uuid=catalog-service' \
2  -H 'Content-Type: application/vnd.pubnub.objects.membership+json;version=1' \
3  -d '{
4    "data": {
5      "channelId": "channel-summer-sale",
6      "userId": "user-alice",
7      "relationshipClassVersion": 1,
8      "payload": { "role": "viewer" }
9    }
10  }'

If the channel or the user doesn't exist, the request returns a 404. A duplicate membership returns a 409.

Refer to Create membership (REST) for the full parameter reference.

Create a relationship

A relationship links two entities through a relationship class you define. This example adds product-sneaker-42 to Alice's wishlist through the Wishlist class from Define a relationship class. Both entities must already exist, and each must match the class that its side of the relationship allows.

• JavaScript
• C#

1const relationship = await pubnub.dataSync.createRelationship({
2    id: 'wishlist-alice-sneaker',
3    class: 'Wishlist',
4    entityAId: 'user-alice',
5    entityBId: 'product-sneaker-42',
6    data: {
7        classVersion: 1,
8        payload: { addedFrom: 'summer-sale' },
9    },
10})

entityAId must be a MarketplaceUser and entityBId must be a Product, because the Wishlist class restricts both sides. An entity of another class is rejected with a 400 and error code DS-0800.

Refer to Create relationship (REST) for the full parameter reference.

Related tasks

• Use optimistic concurrency with ETags. Protect updates and deletes from stale writes.