edit-icon download-icon

Topic APIs

Last Updated: Mar 31, 2017

CreateTopic

Description

This API is used to create a new topic.

A topic name is a string of no more than 256 characters, including letters, numbers, and hyphens (-). It must start with a letter or number.

Request

A request mainly includes the following parts:

  • Request line

    PUT /topics/$TopicName HTTP/1.1

  • Special Request Header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format and contains the created topic attributes.

Parameter name Description Parameter value Required/Optional
MaximumMessageSize Maximum body length of a message sent to the topic, in the unit of bytes An integer in the range of 1,024 (1 KB) to 65, 536 (64 KB); default value: 65,536 (64 KB) Optional
LoggingEnabled Whether to enable log management. “True” indicates that log management is enabled, whereas “False” indicates that log management is disabled. True/False; default value: False Optional

Response

The returned message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 201 Created

    Duplicate topic names are not allowed for the same owner in the same region. If the created topic has the same name and attributes as an existing topic, Status Code 204 (No Content) is returned; if only the names are the same but the attributes are different, Status Code 409 (Conflict) is returned.

  • Special Response Header

Parameter name Description
Location URL of the created topic, in the following format: http://$AccountId.mns.<Region>.aliyuncs.com/topics/$TopicName

For the other response headers, refer to Call Method/Public Parameters.

  • Response Body

    None

Special Error

Error code Error message Status code
TopicAlreadyExist The topic you want to create is already exists. 409
TopicNameLengthError Topic name length is out of range, should be between 1 and 256. 400

Request example:

  1. PUT /topics/$TopicName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 05:57:57 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization:MNS 15B4D3461F177624206A:eCtaUwfGS0oEfznzJEhWFxpf2yk=
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Topic xmlns="http://mns.aliyuncs.com/doc/v1/">
  8. <MaximumMessageSize>10240</MaximumMessageSize>
  9. <LoggingEnabled>True</LoggingEnabled>
  10. </Topic>

Response example:

  1. HTTP/1.1 201 Created
  2. x-mns-request-id:56667165B2B71C9C16000013
  3. x-mns-version: 2015-06-06
  4. Location: http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName

SetTopicAttributes

Description

This API is used to modify topic attributes.

Request

A request mainly includes the following parts:

  • Request line

    PUT /topics/$TopicName?metaoverride=true HTTP/1.1

  • Special URI parameters

    metaoverride=true: The attributes of the topic will be modified.

  • Special Request Header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format and contains the configured topic attributes.

Parameter name Description Parameter value Required/Optional
MaximumMessageSize Maximum body length of a message sent to the topic, in the unit of bytes An integer in the range of 1,024 (1 KB) to 65,536 (64 KB) Optional
LoggingEnabled Whether to enable log management. “True” indicates that log management is enabled, whereas “False” indicates that log management is disabled. True/False Optional

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

  • Special Response Header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    None

Special Error

Error code Error message Status code
TopicNotExist The topic you provided does not exist. 404

Request example:

  1. PUT /topics/$TopicName?metaoverride=true HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. x-mns-version: 2015-06-06
  4. Date: Tue, 08 Dec 2015 06:01:00 GMT
  5. Authorization:MNS 15B4D3461F177624206A:SeIRcZk3lKiP7bl19WB9Uz07bI8=
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Topic xmlns="http://mns.aliyuncs.com/doc/v1/">
  8. <MaximumMessageSize>65536</MaximumMessageSize>
  9. <LoggingEnabled>True</LoggingEnabled>
  10. </Topic>

Response example:

  1. HTTP/1.1 204 No Content
  2. x-mns-request-id:5666721CB2B71C9C1600001B
  3. x-mns-version: 2015-06-06

GetTopicAttributes

Description

This API is used to obtain the attributes of an existing topic. The returned attributes include the attributes that are configured during topic creation, as well as the message retention period and topic creation time.

Request

A request includes the following parts:

  • Request line

    GET /topics/$TopicName HTTP/1.1

  • Special request header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    None

Response

  1. The response message includes three parts: return status line, HTTP header, and message body.
  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    The returned results are in the following XML format: <TopicAttributes>Attribute Element List</TopicAttributes>.

The attribute element list includes:

Parameter name Description
TopicName Name of a topic
CreateTime Time when a topic is created, defined as the number of seconds that have elapsed since 00:00:00, January 1, 1970
LastModifyTime Last modification time of topic attributes, defined as the number of seconds that have elapsed since 00:00:00, January 1, 1970
MaximumMessageSize Maximum body length of a message published to the topic, in the unit of bytes
MessageRetentionPeriod Maximum lifetime of a message in the topic, defined as the number of seconds that have elapsed since the message publishing time. After the time indicated by this parameter expires, the message will be deleted no matter whether it has been successfully pushed to a user.
MessageCount Number of messages in the topic
LoggingEnabled Whether to enable log management. “True” indicates that log management is enabled, whereas “False” indicates that log management is disabled.

Special Error

Error code Error message Status code
TopicNotExist The topic you provided does not exist. 404

Request example:

  1. GET /topics/$TopicName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:02:33 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization:MNS 15B4D3461F177624206A:aVZgLZzVchjOtM1aecDQYFuj4Bo=

Response example:

  1. HTTP/1.1 200 OK
  2. Content-Type=text/xml;utf-8
  3. Content-Length:145
  4. x-mns-request-id:56667279B2B71C9C1600001D
  5. x-mns-version: 2015-06-06
  6. <?xml version="1.0" encoding="UTF-8"?>
  7. <Topic xmlns=http://mns.aliyuncs.com/doc/v1/”>
  8. <TopicName>$TopicName</TopicName>
  9. <CreateTime>1449554277</CreateTime >
  10. <LastModifyTime>1449554460</LastModifyTime>
  11. <MaximumMessageSize>65536</MaximumMessageSize>
  12. <MessageRetentionPeriod>86400</MessageRetentionPeriod>
  13. <MessageCount>0</MessageCount>
  14. <LoggingEnabled>True</LoggingEnabled>
  15. </Topic>

DeleteTopic

Description

This API is used to delete an existing topic.

NOTE:

  1. Be cautious when using this API. After a topic is deleted, all messages in the topic and subscriptions to the topic are also deleted and cannot be recovered.

Request

  1. A request includes the following parts:
  • Request line

    DELETE /topics/$TopicName HTTP/1.1

  • Special Request Header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    None

Response

  1. The response message includes three parts: return status line, HTTP header, and message body.
  • HTTP Status Code

    HTTP/1.1 204 No Content

    If the topic to be deleted does not exist, Status Code 204 is returned and the Delete operation is successful.

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    None

Request example:

  1. DELETE /topics/$TopicName HTTP/1.1
  2. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  3. Date: Tue, 08 Dec 2015 06:05:08 GMT
  4. Authorization: MNS 15B4D3461F177624206A:xit63dyKs83PTJF0hx3fd04CWog=
  5. x-mns-version: 2015-06-06

Response example:

  1. HTTP/1.1 204 No Content
  2. x-mns-request-id: 56667314B2B71C9C16000021
  3. x-mns-version: 2015-06-06

ListTopic

Description

This API is used to list the topics of an account. Querying by page is supported. To acquire a list of topics based on a specific prefix, set the x-mns-prefix parameter when calling this API.

Tips:

If the total number of topics returned for the current request exceeds the x-mns-ret-number value, the returned XML results include NextMarker to indicate the starting position of the next page, and this value is assigned to the x-mns-marker parameter in the next request to display the next page.

Request

A request includes the following parts:

  • Request line

    GET /topics HTTP/1.1

  • Special request header

Parameter name Description Required/Optional
x-mns-marker Starting position of the next page, which is acquired from NextMarker on the previous page Optional
x-mns-ret-number Maximum number of subscriptions returned for a single request, which is an integer in the range of 1 to 1,000. The default value is 1,000. Optional
x-mns-prefix Search for the topic names starting with the specified prefix Optional
  1. For details about other parameters, refer to **Call Method/Public Parameters**.
  • Request Body

    None

Response

  1. The response message includes three parts: return status line, HTTP header, and message body.
  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special response header

    None. For details, refer to Call method/Public parameters.

  • Response Body

    The returned results are in XML format. The top-layer Topics element contains multiple Topic elements, and each Topic element contains the TopicURL element indicating the URL of the topic.If the number of returned queues exceeds the x-mns-ret-number value, the NextMarker element is included to indicate the starting position of the next page.

Request example:

  1. GET /topics HTTP/1.1
  2. x-mns-ret-number:2
  3. Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
  4. Date: Tue, 08 Dec 2015 05:59:22 GMT
  5. Authorization: NS15B4D3461F177624206A:ytChIeJt2klpvFxGCgVsPNI015k=
  6. x-mns-version: 2015-06-06

Response example:

  1. HTTP/1.1 200 OK
  2. x-mns-request-id:566671BAB2B71C9C16000019
  3. x-mns-version: 2015-06-06
  4. <?xml version="1.0" encoding="utf-8"?>
  5. <Topics xmlns="http://mns.aliyuncs.com/doc/v1/">
  6. <Topic>
  7. <TopicURL>http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName1</TopicURL>
  8. </Topic>
  9. <Topic>
  10. <TopicURL>http://$AccountId.mns.cn-hangzhou.aliyuncs.com/topics/$TopicName2</TopicURL>
  11. </Topic>
  12. <NextMarker>OTczNjU4MTcvYmRwejd6NXluby8yNjg0Mi9UZXN0VG9waWMtMy8w</NextMarker>
  13. </Topics>
Thank you! We've received your feedback.