group_members/v3

RESTful style

Administration of Group Members / Distribution Lists

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

Endpoint: /number/group_members/v3/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/group_members/v3/id_box.e1dp4c?user_id=john.smith&cursor=etgyhjklmn>; rel="next"; title*=UTF-8'uk'next_page_with_more_records (Related Links)

X-Name-Base64: Base64-encoded display name of group

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

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.

Unless query has invalid format, DELETE returns HTTP response code 200 (OK) and a counter in.the Response header.

As HTTP DELETE is not supported by HTML5 forms, 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)

NOTE on addressing:

The group_members application uses a normalized format for address field.

To delete a group member, the exact format used in DB must be sent.

While it works to add or update a member like

POST {"address": "0704000001"}

The stored value, returned by GET will be

GET {"address": "sms:+46704000001", "status": "active"}

If you try to delete by sending

DELETE ... ?address=0704000001

- the application may respond with HTTP 200 (OK), but nothing happens