xgroup_members/v1

RESTful style

Administration of Group Members / Distribution Lists

Host URL: https://api.tellustalk.com/

Endpoint: /number/xgroup_members/v1/id_{groupId}

Methods supported: GET, POST, DELETE

Common Headers in all methods:

--------------------------------------------------------------------------------------------------------------------------------------------------------------------

Request Headers:

Accept: application/json (recommended) or application/xml or text/html

Content-Type: application/json (recommended) or application/xml

Response Headers:

Content-Type: application/json or application/xml

Link: </number/xgroup_members/v1/id_box.e1dp4c?user_id=john.smith&cursor=etgyhjklmn>; rel="next"; title*=UTF-8'uk'next_page_with_more_records (Related Links)

---------------------------------------------------------------------------------------------------------------------------------------------------------------------

Member:

Each group member consists of 'address', 'name' and 'status' properties.

GET Method:

To retrieve a list of members (items). In the “happy” (or non-error case), GET returns a representation in XML or JSON, an HTTP response code of 200 (OK) and

some counters in.the Response header.

Request Parameters:

Common request parameters, used as search filters (similar to SQL 'WHERE' clause), and their description are given below:

Response Headers: (Besides response header fields given above, in case of GET method, the following fields are returned)

X-Total-Count: 18 (total number of member records = active +blocked)

X-Active-Count: 10 (total number of active members)

X-Blocked-Count: 8 (total number of blocked members)

X-Unsubscribed-Count: 1 (total number of unsubscribed members)

Response Data:

A list of members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.

Examples:

POST Method:

To create and update group members. In case of success, POST returns an HTTP response code of 200 (OK) and some counters in.the Response header.

Request Data:

A list of members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.

Examples:

Request Body Parameters:

Each group member consists of 'address', 'name' and 'status' properties.

POST data scenarios:

Scenario A: (Invalid Address or request)

Nothing will be added or updated and the member record will be returned as response data.

Scenario B: (Insert new member -> address does not exist in the group)

The member is saved (Member added).

Scenario C: (Update member -> address is already there in the group)

Case 1: If no "status" and "name" are provided, nothing will be updated (Member already exists).

Case 2: If "name" provided is different from the existing "name", the friendly name of the member will be updated (Member updated).

Case 3: If provided status is "active" and the existing status is "blocked", it is activate request (Member updated).

Case 4: If provided status is "blocked" and the existing status is "active", it is blocked request (Member updated).

Response Headers: (Besides response header fields given above, in case of POST method, the following fields are returned)

X-Total-Count: 18 (total number of valid members attempted)

X-Added-Count: 8 (number of new members created)

X-Updated-Count: 2 (number of members updated)

X-AlreadyExist-Count: 8 (number of members already exist)

Response Data:

A list of invalid members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.

DELETE Method:

This method is used to delete group members. In case of success, DELETE returns an HTTP response code of 200 (OK) and a counter in.the Response header.

As HTTP DELETE is not supported by HTML5, there are two ways, delete can be faked, either using HTTP GET or POST.

Request Headers: (Besides request header fields given above, in case of data posted in the body (using POST to fake DELETE), the following field need to be provided)

X-HTTP-Method-Override: DELETE

Response Headers: (Besides response header fields given above, the following fields are returned)

X-Total-Count: 2 (number of members deleted)