GoGo V4 Objects (BETA) API Reference for Realtime Apps

 

These docs are for PubNub 4.0 for Go which is our latest and greatest! For the docs of the older versions of the SDK, please check PubNub 3.0 for Go.

If you have questions about the PubNub for Go SDK, please contact us at support@pubnub.com.

Creates a user with the specified properties. Returns the created user object, optionally including the user's custom data object.

To Create a User you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesThe user ID. Must be unique, and is limited to 36 characters.
NamestringYesDisplay name for the user. Maximum 200 characters.
ExternalIDstringOptionalUser's identifier in an external system
ProfileURLstringOptionalThe URL of the user's profile picture
EmailstringOptionalThe user's email address. Maximum 80 characters.
Custommap[string]interface{}OptionalMap of string and interface with supported data types. Values must be scalar only; arrays or objects are not supported.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex user attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testuser"
name := "name"
extid := "extid"
purl := "profileurl"
email := "email"

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"

incl := []pubnub.PNUserSpaceInclude{
	pubnub.PNUserSpaceCustom,
}

res, status, err := pn.CreateUser().Include(incl).ID(id).Name(name).ExternalID(extid).ProfileURL(purl).Email(email).Custom(custom).Execute()

fmt.Println(res, status, err)
The CreateUser() operation returns a PNCreateUserResponse which contains the following parameters:
Property NameTypeDescription
DataPNUserDetails of type PNUser are here.
Property NameTypeDescription
IDstringThe user ID.
NamestringDisplay name for the user.
ExternalIDstringUser's identifier in an external system.
ProfileURLstringThe URL of the user's profile picture.
EmailstringThe user's email address.
Custommap[string]interfaceMap of string and interface with supported data types.
CreatedstringCreated date.
UpdatedstringLast updated date.
ETagstringThe ETag.

Updates a user with the specified properties. Returns the updated user object, optionally including the user's custom data object.

To Update a User you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesUnique identifier of the user to be updated. You cannot change the user ID.
NamestringOptionalDisplay name for the user. Maximum 200 characters.
ExternalIDstringOptionalUser's identifier in an external system
ProfileURLstringOptionalThe URL of the user's profile picture
EmailstringOptionalThe user's email address. Maximum 80 characters.
Custommap[string]interface{}OptionalMap of string and interface with supported data types. Values must be scalar only; arrays or objects are not supported.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex user attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testuser"
name := "name"
extid := "extid"
purl := "profileurl"
email := "email"

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"

incl := []pubnub.PNUserSpaceInclude{
	pubnub.PNUserSpaceCustom,
}

res, status, err := pn.UpdateUser().Include(incl).ID(id).Name(name).ExternalID(extid).ProfileURL(purl).Email(email).Custom(custom).Execute()

fmt.Println(res, status, err)
The UpdateUser() operation returns a PNUpdateUserResponse which contains the following parameters:
Property NameTypeDescription
DataPNUserDetails of type PNUser are here.

Deletes the specified user object.

To Delete a User you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesThe user ID of the user to delete.
id := "testuser"

res, status, err := pn.DeleteUser().ID(id).Execute()
fmt.Println(res, status, err)
The DeleteUser() operation returns a PNDeleteUserResponse which contains the following parameters:
Property NameTypeDescription
Datainterface{}Returns an empty interface.

Returns a paginated list of user objects, optionally including each user's custom data object.

To Get Users you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
FilterstringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex user attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
incl := []pubnub.PNUserSpaceInclude{
    pubnub.PNUserSpaceCustom,
}

res, status, err := pn.GetUsers().Include(incl).Limit(100).Count(true).Execute()
fmt.Println(res, status, err)
The GetUsers() operation returns a PNGetUsersResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNUserDetails of type PNUser are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.

Returns the specified user object, optionally including the user's custom data object.

To Get User you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesThe user ID of the user to retrieve.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex user attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testuser"
incl := []pubnub.PNUserSpaceInclude{
    pubnub.PNUserSpaceCustom,
}

res, status, err := pn.GetUser().Include(incl).ID(id).Execute()
fmt.Println(res, status, err)
The GetUser() operation returns a PNGetUserResponse which contains the following parameters:
Property NameTypeDescription
DataPNUserDetails of type PNUser are here.

Creates a space with the specified properties. Returns the created space object, optionally including the space's custom data object.

To Create a Space you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesUnique identifier of the space.
NamestringYesDisplay name of the space.
DescriptionstringOptionalDescription of the space.
Custommap[string]interface{}OptionalMap of string and interface with supported data types. Values must be scalar only; arrays or objects are not supported.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex space attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testspace"
name := "name"
desc := "desc"

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"

incl := []pubnub.PNUserSpaceInclude{
	pubnub.PNUserSpaceCustom,
}

res, status, err := pn.CreateSpace().Include(incl).ID(id).Name(name).Description(desc).Custom(custom).Execute()
fmt.Println(res, status, err)
The CreateSpace() operation returns a PNCreateSpaceResponse which contains the following parameters:
Property NameTypeDescription
DataPNSpaceDetails of type PNSpace are here.
Property NameTypeDescription
IDstringThe space ID.
NamestringDisplay name for the space.
DescriptionstringDescription of the space.
Custommap[string]interfaceMap of string and interface with supported data types.
CreatedstringCreated date.
UpdatedstringLast updated date.
ETagstringThe ETag.

Updates a space with the specified properties. Returns the updated space object, optionally including the space's custom data object.

To Update a Space you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesUnique identifier of the space to be updated. You cannot change the space ID.
NamestringYesDisplay name of the space.
DescriptionstringOptionalDescription of the space.
Custommap[string]interface{}OptionalMap of string and interface with supported data types. Values must be scalar only; arrays or objects are not supported.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex space attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testspace"
name := "name"
desc := "desc"

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"

incl := []pubnub.PNUserSpaceInclude{
	pubnub.PNUserSpaceCustom,
}

res, status, err := pn.UpdateSpace().Include(incl).ID(id).Name(name).Description(desc).Custom(custom).Execute()
fmt.Println(res, status, err)
The UpdateSpace() operation returns a PNUpdateSpaceResponse which contains the following parameters:
Property NameTypeDescription
DataPNSpaceDetails of type PNSpace are here.

Deletes the specified space object.

To Delete a Space you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesThe space ID to delete.
id := "testspace"

res, status, err := pn.DeleteSpace().ID(id).Execute()
fmt.Println(res, status, err)
The DeleteSpace() operation returns a PNDeleteUserResponse which contains the following parameters:
Property NameTypeDescription
Datainterface{}Returns an empty interface.

Returns the paginated list of space objects, optionally including the space's custom data object.

To Get Spaces you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
FilterstringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex space attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
incl := []pubnub.PNUserSpaceInclude{
    pubnub.PNUserSpaceCustom,
}

res, status, err := pn.GetSpaces().Include(incl).Limit(100).Count(true).Execute()
fmt.Println(res, status, err)
The GetSpaces() operation returns a PNGetSpacesResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNSpaceDetails of type PNSpace are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.

Returns the specified space object, optionally including the space's custom data object.

To Get a Space you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
IDstringYesThe Space ID to retrieve.
Include[]pubnub.PNUserSpaceIncludeOptionalList of additional/complex space attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNUserSpaceCustom
id := "testspace"
incl := []pubnub.PNUserSpaceInclude{
    pubnub.PNUserSpaceCustom,
}

res, status, err := pn.GetSpace().Include(incl).ID(id).Execute()
fmt.Println(res, status, err)
The GetSpace() operation returns a PNGetSpaceResponse which contains the following parameters:
Property NameTypeDescription
DataPNSpaceDetails of type PNSpace are here.

Get the specified user's space memberships.

To Get Memberships you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
UserIDstringYesUnique identifier of the user whose memberships you wish to retrieve.
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
FilterstringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
Include[]pubnub.PNMembershipsIncludeOptionalList of additional/complex attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNMembershipsCustom, pubnub.PNMembershipsSpace, pubnub.PNMembershipsSpaceCustom
inclMemberships := []pubnub.PNMembershipsInclude{
	pubnub.PNMembershipsCustom,
	pubnub.PNMembershipsSpace,
	pubnub.PNMembershipsSpaceCustom,
}

res, status, err := pn.GetMemberships().UserID("testuser").Include(inclMemberships).Limit(100).Count(true).Execute()
fmt.Println(res, status, err)
The GetMemberships() operation returns a PNGetMembershipsResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNMembershipsDetails of type PNMemberships are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.
Property NameTypeDescription
IDstringThe user ID.
SpacePNSpaceDetails of type PNSpace are here.
Custommap[string]interfaceMap of string and interface with supported data types.
CreatedstringCreated date.
UpdatedstringLast updated date.
ETagstringThe ETag.

Get the specified space’s member users.

To Get Members you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
SpaceIDstringYesUnique identifier of the space whose memberships you wish to retrieve.
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
FilterstringOptionalExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.

In addition to custom attributes, the expressions can refer to attributes on associated entities one level deep (that is, the association and its target entities).
Include[]pubnub.PNMembersIncludeOptionalList of additional/complex attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNMembersCustom, pubnub.PNMembersUser, pubnub.PNMembersUserCustom
inclSm := []pubnub.PNMembersInclude{
	pubnub.PNMembersCustom,
	pubnub.PNMembersUser,
	pubnub.PNMembersUserCustom,
}

res, status, err := pn.GetMembers().SpaceID("testspace").Include(inclSm).Limit(100).Count(true).Execute()
fmt.Println(res, status, err)
The GetMembers() operation returns a PNGetMembersResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNMembersDetails of type PNMembers are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.
Property NameTypeDescription
IDstringThe space ID.
UserPNUserDetails of type PNUser are here.
Custommap[string]interfaceMap of string and interface with supported data types.
CreatedstringCreated date.
UpdatedstringLast updated date.
ETagstringThe ETag.

Manage the specified user's memberships. You can Add, Remove, and Update a user's memberships.

To Manage Memberships you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
UserIDstringYesUnique identifier of the user whose memberships you wish to manage.
Addpubnub.PNMembershipsInputOptionalStruct of type pubnub.PNMembershipsInput to be added for the specified user. In PNMembershipsInput you can set the SpaceID and a Custom map.
Updatepubnub.PNMembershipsInputOptionalStruct of type pubnub.PNMembershipsInput to be updated for the specified user. In PNMembershipsInput you can set the SpaceID and a Custom map.
Removepubnub.PNMembershipsRemoveOptionalStruct of type pubnub.PNMembershipsRemove to be removed for the specified user. In PNMembershipsRemove you can set the SpaceID
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
Include[]pubnub.PNMembershipsIncludeOptionalList of additional/complex attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNMembershipsCustom, pubnub.PNMembershipsSpace, pubnub.PNMembershipsSpaceCustom
inclMemberships := []pubnub.PNMembershipsInclude{
    pubnub.PNMembershipsCustom,
    pubnub.PNMembershipsSpace,
    pubnub.PNMembershipsSpaceCustom,
}

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"


inputMem := pubnub.PNMembershipsInput{
	ID:     "testspace",
	Custom: custom,
}

inputArrMem := []pubnub.PNMembershipsInput{
	inputMem,
}

res, status, err := pn.ManageMemberships().UserID("testuser").Add(inputArrMem).Update([]pubnub.PNMembershipsInput{}).Remove([]pubnub.PNMembershipsRemove{}).Include(inclMemberships).Limit(100).Count(true).Execute()

fmt.Println(res, status, err)
The ManageMemberships() operation returns a PNManageMembershipsResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNMembershipsDetails of type PNMemberships are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.

Manage the specified space’s member users. You can Add, Remove, and Update a space's members.

To Manage Members you can use the following method(s) in the Go V4 SDK:
ParameterTypeRequiredDescription
SpaceIDstringYesUnique identifier of the space whose members you wish to manage.
Addpubnub.PNMembersInputOptionalStruct of type pubnub.PNMembersInput to be added for the specified space. In PNMembersInput you can set the UserID and a Custom map.
Updatepubnub.PNMembersInputOptionalStruct of type pubnub.PNMembersInput to be updated for the specified space. In PNMembersInput you can set the UserID and a Custom map.
Removepubnub.PNMembersRemoveOptionalStruct of type pubnub.PNMembersRemove to be removed for the specified space. In PNMembersRemove you can set the UserID
LimitintOptionalMaximum number of results to return per page. Default 100.
CountboolOptionalRequest TotalCount to be included in paginated response. Default false
StartstringOptionalPreviously-returned cursor bookmark for fetching the next page.
EndstringOptionalPreviously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.
Include[]pubnub.PNMembersIncludeOptionalList of additional/complex attributes to include in response. Omit this parameter if you don't want to retrieve additional attributes.
Available values: pubnub.PNMembersCustom, pubnub.PNMembersUser, pubnub.PNMembersUserCustom
inclSm := []pubnub.PNMembersInclude{
    pubnub.PNMembersCustom,
    pubnub.PNMembersUser,
    pubnub.PNMembersUserCustom,
}

custom := make(map[string]interface{})
custom["a"] = "b"
custom["c"] = "d"


inputMem := pubnub.PNMembersInput{
	ID:     "testuser",
	Custom: custom,
}

inputArrMem := []pubnub.PNMembersInput{
	inputMem,
}

res, status, err := pn.ManageMembers().SpaceID("testspace").Add(inputArrMem).Update([]pubnub.PNMembersInput{}).Remove([]pubnub.PNMembersRemove{}).Include(inclSm).Limit(100).Count(true).Execute()

fmt.Println(res, status, err)
The ManageMembers() operation returns a PNManageMembersResponse which contains the following parameters:
Property NameTypeDescription
Data[]PNMembersDetails of type PNMembers are here.
TotalCountintTotal count of objects without pagination.
NextstringCursor bookmark for fetching next page.
PrevstringCursor bookmark for fetching prev page.

The filtering language for Objects is similar to the stream filtering language.

Note the following:

  • Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.
  • Custom properties must have the same type as the value used in the expression; it is an error to compare a custom property of one type to a value of another type.
  • Objects that do not have the referenced custom property at all are excluded regardless of the operator or value used in the expression. The null value can be used to filter out objects that do or do not have the referenced custom property.
  • The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.
  • Values used with LIKE must be properly encoded just like any other string value. Thus, in order to escape an asterisk, the raw value must contain \\*.
  • The entire expression must be properly URL-encoded when used in the query string.

<expression>           ::= <and_expression> ( "||" <and_expression> )*
<and_expression>       ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition>     ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path>        ::= <property_name> ( "." <property_name> )*
<property_name>        ::= <identifier> | "[" <string> "]"
<value>                ::= <string> | <number> | "true" | "false" | "null"

Tokens

<identifier>           ::=  <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator>  ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string>               ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - <double_quote> - "\" )* <double_quote>
                            | "'" ( "\" "'" | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - "'" - "\" )* "'"
<number>               ::= ( "+" | "-" )? ( <digit> )* ( "." )? <digit> ( <digit> )* 
                            ( "e" | "E" ( "+" | "-" )? <digit> ( <digit> )* )?
<letter>               ::= Unicode Letter (category; any kind of letter from any language)
<digit>                ::= "0" .. "9"
<hex_digit>            ::= <digit> | "A" .. "F"
<double_quote>         ::= the " character
<unicode_char>         ::= any character in the Unicode range from U+0020 to U+10FFFF inclusive
<special_char>         ::= "\" | "/" | "b" | "f" | "n" | "r" | "t"

The following simple expression returns results whose custom property named public is equal to Boolean true.


custom.public == true

The following date/time comparison returns results that were modified on or after August 31st, 2019 (UTC):


updated >= "2019-08-31T00:00:00Z"

The following compound expression returns results that don't have a description, but do have a non-empty custom label or description property:


description == null && (custom.label != "" || custom.description != "")

The following wildcard expression returns results whose name starts with the letter X:


name LIKE 'X*'

The following escaped wildcard expression returns results whose name contains an asterisk:


name LIKE '*\\**'