Topic

Location /api/apps/{appID}/topics/{topicID}
This resource represents a topic in an application, user group or thing (depending on the scope).

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

PUT

/api/apps/{appID}/topics/{topicID}

Description

Create a new topic. The topicID must be an string following the pattern [A-Za-z0-9_-]* and with maximum length of 64 characters.

Security

The administrator can execute this action. For other users, the permission to execute this action depends on the ACL of the scope (application, user, group, or thing) where the topic belongs.

Note

This request requires empty body.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
topicID Yes string topicID of the topic being accessed
Responses
204

Content-Type (None)

Topic created successfully
Note This response has no contents.
409

Content-Type application/vnd.kii.TopicAlreadyExistsException+json

A topic with the same topicID already exists.
Contents
Name Type Description
errorCode string Error code "TOPIC_ALREADY_EXISTS".
message string The error message.
topicID string The ID of the topic that already exists
objectScope ObjectScope The scope of the topic
appID string The ID of the application.
userID string The ID of the user. Only provided for a user-scope bucket.
groupID string The ID of the group. Only provided for a group-scope bucket.
thingID string The ID of the thing. Only provided for a thing-scope bucket.
type string One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING".
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to create the topic.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

GET

/api/apps/{appID}/topics/{topicID}

Description

Response 200 is for getting the topic, but currently does not returns any value and acts like head method.

Security

Can not be performed accessing as anonymous.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
topicID Yes string topicID of the topic being accessed
Responses
204

Content-Type (None)

The topic exists.
Note This response has no contents.
404

Content-Type application/vnd.kii.TopicNotFoundException+json

The topic did not exist.
Contents
Name Type Description
errorCode string Error code "TOPIC_NOT_FOUND".
message string The error message.
topicID string The ID of the topic that is not found
objectScope ObjectScope The scope of the topic
appID string The ID of the application.
userID string The ID of the user. Only provided for a user-scope bucket.
groupID string The ID of the group. Only provided for a group-scope bucket.
thingID string The ID of the thing. Only provided for a thing-scope bucket.
type string One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING".
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to check if the topic exists.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

HEAD

/api/apps/{appID}/topics/{topicID}

Description

Check the topic exists.

Security

Can not be performed accessing as anonymous.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
topicID Yes string topicID of the topic being accessed
Responses
204

Content-Type (None)

The topic exists.
Note This response has no contents.
404

Content-Type (None)

The topic does not exist.
401

Content-Type (None)

Not authorized to check if the topic exists.

DELETE

/api/apps/{appID}/topics/{topicID}

Description

Delete the topic with all the subscriptions it has.

Security

Can be performed by the administrator, the creator of the topic and the scope owner (the group owner if the topic is in a group or the user owner if the topic belongs to a user).

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
topicID Yes string topicID of the topic being accessed
Responses
204

Content-Type (None)

The topic has been deleted successfully.
Note This response has no contents.
404

Content-Type application/vnd.kii.TopicNotFoundException+json

The topic was not found.
Contents
Name Type Description
errorCode string Error code "TOPIC_NOT_FOUND".
message string The error message.
topicID string The ID of the topic that is not found
objectScope ObjectScope The scope of the topic
appID string The ID of the application.
userID string The ID of the user. Only provided for a user-scope bucket.
groupID string The ID of the group. Only provided for a group-scope bucket.
thingID string The ID of the thing. Only provided for a thing-scope bucket.
type string One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING".
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to delete the topic.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).