SDK updated for API 0.4

[oxnr]

Overview

In general this will update the SDK to version 1.1 being compatible with the Tapglue API 0.4.

• UGC API with Posts, Comments & Likes
• New Feed API with Newsfeed, Posts Feed & Events Feed
• New Connections API with Friends Confirmation
• Multi-User Search (by Email & SocialIds)
• Queries for all Feeds
• Add tests for new methods
• Add new functions to sample app (posts & comments only)

As in the project before. The iOS SDK is the template/blueprint for the Implementation if the following document is missing specification details. The documentation regarding the iOS details can be found here.

New models

The new models for this API version contain:

• Posts
• Comments
• Likes

The specification and attributes of the new entities are below.

New Endpoints

The endpoints that are currently missing are specified in this document. This document the most important in this specification as it shows all the gaps and differences in the current Android SDK.

Naming inconsistencies are also marked (red) in that document. They should be aligned with the iOS SDK API, wherever reasonable.

Basic

This section describes the basic changes that need to be done.

Version

• Update SDK version everywhere from 1.0 to 1.1.0

User

• Add setUnhashedPassword method to user to set a password that is not PBKDF2 hashed.

Event

• Add the string attribute tg_object_id to the events model.

Restructuring

• Change Tapglue.connections() to Tapglue.connection() (singular to be consistent)
• Move following methods from feed() to connection():
• Tapglue.feed().retrieveFollowersForCurrentUser
• Tapglue.feed().retrieveFollowersForUser
• Tapglue.feed().retrieveFollowsForCurrentUser
• Tapglue.feed().retrieveFollowsForUser
• Tapglue.feed().retrieveFriendsForCurrentUser
• Tapglue.feed().retrieveFriendsForUser

Connections

• Rename unFriend to unfriend
• Rename unFollow to unfollow
• Add Tapglue.connection().retrieveConfirmedConncetionsForCurrentUser
• Add Tapglue.connection().retrieveRejectedConncetionsForCurrentUser

Posts, Comments & Likes API

We've added a new API for Posts, Comments on Posts and Likes on Posts and Shares of Posts.

The API now allows the creation of posts. Posts support the basic CRUD as well as retrieving a list of posts for different endpoints.

Methods

Following methods should be available after the implementation of the Posts API.

Posts

• Tapglue.post().createPost
• Tapglue.post().getPost
• Tapglue.post().updatePost
• Tapglue.post().deletePost

Comments

• Tapglue.post()createComment
• Tapglue.post().updateComment
• Tapglue.post().deleteComment

Likes

• Tapglue.post().createLike
• Tapglue.post().deleteLike

Model

The following section describes the models for Posts, Comments and Likes.

Posts

Write

Key	Type	Description	Example
tags	array	Contains an array of strings which describe tags of a post	"tags": ["fitness","running"]
visibility	int	Visibility of posts (10,20,30)	"visibility": 30
attachments	array	Contains various attachments of a post (text, url)	example below

Attachments example

"attachments": [
      {
        "content": "http://bit.ly/123gif",
        "name": "teaser",
        "type": "url"
      },
      {
        "content": "Lorem ipsum...",
        "name": "body",
        "type": "text
      }
    ],
    "tags": [
      "review"
    ]

The attachment structure is always the same:

• content
• name
• type

currently we support text and url as the type. In the future we will allow more types such as audio, video, image etc. In this case content will always be a url.

Read only

Key	Type	Description	Example
id	string	Id of the post	"id": "12743631303647839"
user_id	string	Id of the user who created post	"user_id": "11286878691041887"
is_liked	bool	Flag wether the posts is liked or not	"is_liked": true
created_at	string	Created at date	"created_at": "2015-11-27T16:03:36.171840385Z"
updated_at	string	Created at date	"updated_at": "2015-11-27T16:03:36.171840478Z

The user of the post should be accessible like in events Post.user.username etc.

Addition read only keys for counts are:

  "counts": {
    "comments": 3,
    "likes": 12,
    "shares": 1
  }

We don't return the counts yet. So the values should just be 0 if nothing is being returned from the API. However we will soon enable this feature from our backend

Comments

Write

Key	Type	Description	Example
content	string	Content of the comment	"content": "very nice post!"

Read only

Key	Type	Description	Example
id	string	Id of the like	"id": "12743631303647840"
post_id	string	Id of the post	"id": "12743631303647839"
user_id	string	Id of the user who created post	"user_id": "11286878691041887"
created_at	string	Created at date	"created_at": "2015-11-27T16:03:36.171840385Z"
updated_at	string	Created at date	"updated_at": "2015-11-27T16:03:36.171840478Z

Likes

Read only

Key	Type	Description	Example
id	string	Id of the comment	"id": "12743631303647840"
post_id	string	Id of the post	"id": "12743631303647839"
user_id	string	Id of the user who created post	"user_id": "11286878691041887"
created_at	string	Created at date	"created_at": "2015-11-27T16:03:36.171840385Z"
updated_at	string	Created at date	"updated_at": "2015-11-27T16:03:36.171840478Z

API

Overview of endpoints:

Name	Method	Route
Create Post	POST	/posts
Retrieve Post	GET	/posts/{postID}
Update Post	PUT	/posts/{postID}
Delete Post	DELETE	/posts/{postID}
Retrieve all Posts	GET	/posts
Retrieve Posts Feed	GET	/me/feed/posts
Retrieve my Posts	GET	/me/posts
Retrieve users Posts	GET	/users/{userID}/posts

Name	Method	Route
Create Comment	POST	/posts/{postID}/comments
Update Comment	PUT	/posts/{postID}/comments/{commentID}
Delete Comment	DELETE	/posts/{postID}/comments/{commentID}
Retrieve Comments	GET	/posts/{postID}/comments

Name	Method	Route
Create Like	POST	/posts/{postID}/likes
Delete Like	DELETE	/posts/{postID}/likes
Retrieve Likes	GET	/posts/{postID}/likes

Deletion of likes is idempotent, so there is no id needed.

Post creation

curl -X POST /posts \
  -d $'
  {
    "attachments": [
      {
        "content": "http://bit.ly/123gif",
        "name": "teaser",
        "type": "url"
      },
      {
        "content": "Lorem ipsum...",
        "name": "body",
        "type": "text
      }
    ],
    "tags": [
      "review"
    ],
    "visibility": 30
  }
  '

201 Created
{
  "attachments": [
    {
      "content": "http://bit.ly/123gif",
      "name": "teaser",
      "type": "url"
    },
    {
      "content": "Lorem ipsum...",
      "name": "body",
      "type": "text
    }
  ],
  "id": "12743631303647839",
  "tags": [
    "review"
  ],
  "visibility": 30,
  "user_id": "11286878691041887",
  "created_at": "2015-11-27T16:03:36.171840385Z",
  "updated_at": "2015-11-27T16:03:36.171840478Z"
}

Comment creation

curl -X POST /posts/12743631303647839/comments \
    -d $'
    {
        "content": "Do like.",
    }
    '

201 Created
{
  "content": "Do like.",
  "id": "12743631303647840",
  "post_id": "12743631303647839",
  "user_id": "11286878691041888",
  "created_at": "2015-11-27T16:03:36.171840385Z",
  "updated_at": "2015-11-27T16:03:36.171840478Z"
}

Comment retrieval

curl -X GET /posts/12743631303647839/comments

200 OK
{
  "comments": [
    {
      "content": "Do like.",
      "id": "12743631303647840",
      "post_id": "12743631303647839",
      "user_id": "11286878691041888",
      "created_at": "2015-11-27T16:03:36.171840385Z",
      "updated_at": "2015-11-27T16:03:36.171840478Z"
    }
  ],
  "comments_count": 1,
  "post": {
    "attachments": [
      {
        "content": "http://bit.ly/123gif",
        "name": "teaser",
        "type": "url"
      },
      {
        "content": "Lorem ipsum...",
        "name": "body",
        "type": "text
      }
    ],
    "id": "12743631303647839",
    "tags": [
      "review"
    ],
    "visibility": 30,
    "user_id": "11286878691041887",
    "created_at": "2015-11-27T16:03:36.171840385Z",
    "updated_at": "2015-11-27T16:03:36.171840478Z"
  }
}

Comment deletion

curl -X DELETE /posts/12743631303647839/comments/12743631303647840

204 No Content

Like creation

curl -X POST /posts/12743631303647839/likes \
  -H 'Content-Length: 0'

201 Created
{
    "id": "37363583381716140",
    "post_id": "12743631303647839",
  "user_id": "11286878691041888",
  "created_at":"2015-03-21T14:28:02.4+01:00",
  "updated_at":"2015-03-21T14:28:02.4+01:00"
}

Like retrieval

curl -X GET /posts/12743631303647839/likes

200 OK
{
  "likes": [
    {
      "id": "37363583381716140",
      "post_id": "12743631303647839",
      "user_id": "11286878691041888",
      "created_at":"2015-03-21T14:28:02.4+01:00",
      "updated_at":"2015-03-21T14:28:02.4+01:00"
    }
  ],
  "likes_count": 1,
  "post": {
    "attachments": [
      {
        "content": "http://bit.ly/123gif",
        "name": "teaser",
        "type": "url"
      },
      {
        "content": "Lorem ipsum...",
        "name": "body",
        "type": "text
      }
    ],
    "id": "12743631303647839",
    "tags": [
      "review"
    ],
    "visibility": 30,
    "user_id": "11286878691041887",
    "created_at": "2015-11-27T16:03:36.171840385Z",
    "updated_at": "2015-11-27T16:03:36.171840478Z"
  }
}

Like deletion

curl -X DELETE /posts/12743631303647839/likes/37363583381716140

204 No Content

New search methods

We have a new API that allows to search for multiple emails or socialIDs. Examples:

• Implement new method to search users by multiple emails Tapglue.user().searchUsersWithEmails

curl -X "GET" "https://api.tapglue.com/0.4/users/search?email=jonelle.bowers%40rccgmail.org&email=nu.cardamone%40mycabin.com" \
    -H "Accept: application/json" \
    -H "Authorization: Basic OWQ0ZjgzNjNjZTFmZDExMTM4NDUyMmE5NWNkZjZiM2Y6SzJCT2FTRjRJbU1yWVZGaU9pOUlPWDB2VG1ZPQ==" 

• Implement new method to search users by multiple socialIds Tapglue.user().searchUsersWithSocialUserIds

curl -X "GET" "https://api.tapglue.com/0.4/users/search?social_platform=facebook&socialid=fb54321123&socialid=fb543211234" \
    -H "Accept: application/json" \
    -H "Authorization: Basic OWQ0ZjgzNjNjZTFmZDExMTM4NDUyMmE5NWNkZjZiM2Y6SzJCT2FTRjRJbU1yWVZGaU9pOUlPWDB2VG1ZPQ==" 

The goal is to implement to new methods:

• searchUsersWithEmails (params: emails = [string,string...]
• searchUsersWithSocialIds (params: platform = string socialIds = [string,string,..]

New feed structure

Due to the introduction of posts, the new feed structure changed a little bit.

The new feeds structure will look like the following:

• me/feed -> posts & events
• me/feed/posts -> posts
• me/feed/events -> events

for users

• me/events & users/:userID/events
• me/posts & users/:userID/posts

The new me/feed will have both posts and events. The other endpoints have either posts or events.

The names of the methods should be as follows:

• me/feed -> Tapglue.feed().retrieveNewsFeedForCurrentUser
• me/feed/posts -> Tapglue.feed().retrievePostsFeedForCurrentUser
• me/feed/events -> Tapglue.feed().retrieveEventsFeedForCurrentUser
• me/events -> Tapglue.feed().retrieveEventsForCurrentUser
• users/:userID/events -> Tapglue.feed().retrieveEventsForUser
• me/posts -> Tapglue.feed().retrievePostsForCurrentUser
• users/:userID/posts -> Tapglue.feed().retrievePostsForUser

Feed queries

Besides the default feed() methods above. There should be another additional method that also accepts a query object. The query is a JSON object and need to be attached to endpoint after ?where= clause. Here is an example of a query object:

{  
    "object":{  
        "id":{  
            "eq":"someId"
        }
    },
    "type":{  
        "eq":"someType"
    }
}

The query object always contains the field, that is to be checked (i.e. type) followed by the request condition eq and then the value someType. For now, the only request condition is eq but there are more to come in the future. Fields that are checkable are currently:

• type
• tg_object_id
• object -> id
• object -> type

As a request condition we currently support two:

• eq
• in

eq, contains a single string. in contains an array of strings.

Example for in:

{  
    "type":{  
        "in":["someType","anotherType"]
    }
}

Update tests

• Add appropriate tests for the new methods

Update sample app

• Add posts, comments & likes to sample app.