REST API

Table of Contents

1. General

The following describes the REST API exposed by the InAppSocial server.
Current Version: 1.7
Base URL:
All REST methods exposed by the InAppSocial server are implemented using the following URL format:

http://api.inappsocial.com/Rest<api-version>/<resource-name>

Request requirements:

  • All requests should be based on HTTP, some supporting POST while other GET. see each method description.
  • All POST requests support; attaching a JSON object using the appropriate method dictionary as a payload, as well setting the request parameters directly into the POST form.
  • All POST requests should include the following HTTP header;
Content-Type: application/x-www-form-urlencoded

Response:
All responses bodies are based on JSON format.

Top of Page 

2. Login

Request:

Use POST method to login to the InAppSocial Conversation server using the following URL:

http://api.inappsocial.com/Rest1.7/user/login.json

Request parameters:

  • email
  • password

Response:

The response JSON contains a WyHintToken object, which includes the following fields:

  • createdTime – Indicate when the use was logged in,
  • expireTime – The time when the token will be expired,
  • pid – The person/user id,
  • token – The token that can be used later for re-authentication

Example of response JSON:

{"WyHintToken":	{
		"createdTime": "2012-01-20T13:16:49.729-05:00",
		"expireTime": "2012-01-21T13:16:49.729-05:00",
		"pid": 2,
		"token": "Px1gx34fk21s4k5lghjK2908456sX235dghjk234523
		}
}
Top of Page

3. Get Conversation Stats

Request:

Use http GET method to get the stats of a specific conversation using the following request format;

http://api.inappsocial.com/Rest1.7/conversation/count.json?appId=<application-id>
&contentId=<external-content-id>&token=<user-login-token>

This API is used to retrieve a specific external content’s counts. There are 3 parameters (two mandatory and one optional) in the query string:

  • appId – The application Id assigned to developer during application registry; (mandatory),
  • contentId – The external content Id, which will be checked against; (mandatory),
  • token – The user login token, which was assigned in the response of login request; (optional), the response will show if you have action on this content.

Response:

The JSON response contains all related counts of this content. The JSON object contains the following fields:

  • postCount – How many posts are related to the content,
  • commentCount – How many comments are related to the content,
  • likeCount – How many likes are related to the content,
  • rateCount – How many rates are related to the content,
  • rateScore – How much the rate score (average) is,
  • postedByMe – Indicate if I posted for this content,
  • likedByMe – Indicate if I liked this content,
  • ratedByMe – indicate if I rated this content

Here is an example of response:

{"count":	{
		"commentCount":2,
		"commentedByMe":true,
		"likeCount":1,
		"likedByMe":true,
		"postCount":1,
		"postedByMe":true,
		"rateCount":1,
		"rateScore":0,
		"ratedByMe":true,
		"shareCount":0
		}
}
Top of Page

4. Discover Conversation Types

Overview:
If any specified application has more than one conversation, the client needs to discover them and choose the right one when posting a conversation.

Request:

Use http GET method to get list of conversation types for a specified application from;

http://api.inappsocial.com/Rest1.7/conversation/getTypes.json?appId=<application-id>

The only mandatory parameter in the query string is “appId”, which is the application Id that was assigned to developer during application registry.

Response:

The response is an JSON array, each type will contains:

  • type – the id of the conversation type,
  • name – the name of the conversation

Example of response JSON array:

[{"convType":{"name":"Reviews","type":5}}]
Top of Page

5. List Conversations

Request:
Use http GET method to list all conversations posted to a specific content using the following request format;

http://api.inappsocial.com/Rest1.7/conversation/search.json?appId=<app-id>
&contentId=<external-content-id>

Where;

  • <app-id> is the value of application Id (get from the App Dashboard), it’s a mandatory parameter,
  • <content-id> is the unique content identifier,

Response:

The response is a JSON array of conversations objects each including:

  • appId- the id of the conversation type,
  • id– The id of the specific conversation,
  • conversation - the conversation content posted under the given external content,
  • ownerId – the Id of the person who post the conversation (pid from WyHintToken),
  • contentId– the external Id of the specific content. This can be any specific unique identifier for the content such as a Web url,
  • createdTime– the time of the content publishing date as a string in the format of “yyyy-MM-dd HH:mm:ss”.
  • cTypeId – the conversation type Id (long), which can be discovered from “getTypes” response.

Example of response JSON array:

[
     {
          "subject": {
                     "id": 857,
                     "valid": 0,
                     "createdTime": "2012-06-03T04:37:20Z",
                     "ownerId": 51,
                     "osInfoId": 0,
                     "topicId": 8,
                     "externalContentId": 12345678911,
                     "cmdId": 146,
                     "deviceModelId": 0,
                     "appId": 71,
                     "type": 10,
                     "content": "New opinion test",<
                     "status": 0,
                     "appVersionId": 80
                     }
    },
    {
          "subject": {
                     "id": 255,
                     "rating": {
                                "id": 210,
                                "note": "",
                                "score": 4,
                                "valid": 0,
                                "count": 0,
                                "createdTime": "2012-05-07T22:12:57Z",
                                "ownerId": 51,
                                "itemType": "SUBJECT",
                                "itemId": 255
                                },
                     "valid": 0,
                     "createdTime": "2012-05-02T15:37:04Z",
                     "ownerId": 51,
                     "osInfoId": 0,
                     "topicId": 8,
                     "externalContentId": 12345678911,
                     "cmdId": 146,
                     "deviceModelId": 0,
                     "appId": 71,
                     "type": 10,
                     "content": "Cool and calming image",
                     "status": 0,
                     "appVersionId": 80
                     }
     }
]
Top of Page

6. Post a Conversation

Request:
Use http POST method to post a new conversation to:

http://api.inappsocial.com/Rest1.7/conversation/post.json

A form of conversation object needs to be carried with the POST request.
Here are the fields needed in the post form:

  • contentId – The external content Id – (String),
  • conversation- the conversation content which will be posted for the given external content  – (String),
  • topic- the topic that conversation is about – (String, optional),
  • ownerId – the Id of the person who posted the conversation (pid from WyHintToken) – (Long),
  • appId – The app Id which is assigned to the application during registering application – (String)
  • cTypeId – the conversation type Id, which can be retrieved from the  “getTypes” response  for discovering conversation type – (Long)

Response:
The response of this request contains the full conversation item. Here is an example:

{"subject":{
		"appId": 40,
		"appVersionId": 42,
		"createdTime": "2012-01-19T16:50:03.789-05:00",
		"externalContentId": 1234567,
		"id": 139,
		"ownerId": 1,
		"conversation": "This is an amazing picture"
		"type": 25
		}
}
Top of Page

7. Reply to a Posted Conversation

Request:
Use http POST method to reply to a specific conversation to:

http://api.inappsocial.com/Rest1.7/conversation/reply.json

A form of the reply object needs to be carried with the POST request. The form contains the following three fields:

  • response – the content of the reply,
  • subjectId – the subject Id that has been assigned in the response of “post”,
  • ownerId – the Id of the user who is replying to this conversation.

Response:
The following is an example of JSON response object:

{"response":{
		"content": "good",
		"createdTime": "2012-01-20T14:41:42.684-05:00",
		"id": 48,
		"ownerId": 1,
		"subjectId": 112,
		"valid": 0
		}
}
Top of Page

8. Comment

Request:
Use http POST method to post a comment to a specific conversation to:

http://api.inappsocial.com/Rest1.7/conversation/comment.json

A form of comment needs to be carried with the POST request. The form should contain the following fields:

  • comment – the content of the comment,
  • subjectId – the subject Id that has been assigned in the response of “post”,
  • ownerId – the Id of the user who is commenting on this conversation.

Response:
Example of respone JSON object:

{"comment":{
		"content": "good",
		"createdTime": "2012-01-20T14:41:42.684-05:00",
		"id": 22,
		"itemId": 112
		"itemType": "SUBJECT",
		"ownerId": 1,
		"valid": 0
		}
}
Top of Page

9. Like

Request:
Use http POST method to post a comment to a specific conversation to:

http://api.inappsocial.com/Rest1.7/conversation/like.json

A form of Like needs to be carried with the POST request. The form should contain the following fields:

  • subjectId – the subject Id that has been assigned in the response of “post”,
  • ownerId – the Id of the user who is liking this conversation.

Response:
Here is an example of JSON response :

{"like": {
	 "createdTime": "2012-01-20T14:54:08.123-05:00",
	 "id": 4,
	 "itemId": 112,
	 "itemType": "SUBJECT",
	 "ownerId": 1,
	 "valid" : 0
	 }
}
Top of Page

10. Rate

Request:
Use http POST method to post a rating to a specific conversation to:

http://api.inappsocial.com/Rest1.7/conversation/rate.json

A form of rating needs to be carried with the POST request. The form should contain the following fields:

  • subjectId – the subject Id that has been assigned in the response of “post”,
  • ownerId – the Id of the user who is rating this conversation,
  • score – The score you want to rate the conversation (range 1 to 5),
  • note – the additional note you want to included (This field is optional).

Response:
Here is an example of the JSON response object:

{"rating": {
		"createdTime": "2012-01-20T14:54:08.123-05:00",
		"id": 4,
		"itemId": 112,
		"itemType": "SUBJECT",
		"ownerId": 1,
		"note": "I love this",
		"score": 5,
		"valid" : 0
		}
}
Top of Page

11. Post Content Metadata

Overview:
The InAppSocial server supports uploading content metadata in order to provide better user experience by displaying the conversations in correlation with the posted metadata.
This approach enables user to view a summary when displaying the conversations attached to a specific content using any of the mobile SDKs.
The content metadata can also be posted directly using the SDKs. See individual documentation.
Request:
Use http POST method to post the content metadata that can attach conversations to.

http://api.inappsocial.com/Rest1.7/conversation/metadata/add

A form including the following parameters needs to be carried with the POST request;

  • appId– The id of the application,
  • contentId– the external Id of the specific content. This can be any specific unique identifier for the content such as a Web url,
  • url– the Web url of the content,
  • title– the title of the content,
  • author– the author for the content,
  • summary– a summary for the content in text format,
  • createdTime– the time of the content publishing date as a string in the format of “yyyy-MM-dd HH:mm:ss”,
  • mimeType– the mime type of the attached media. Currently it only supports image format of mime type jpeg (mimeType=image/jpeg), png (mimeType=image/png) and gif (mimeType=image/gif)
  • dataSize– the size of the attached media
  • mediaData– the actual image data as Byte array

Response:
The response include an HTTP status code for success or failure.

Top of Page

12. Fetch Content Metadata

Request:
Use http GET method to get a rating to a specific conversation to:

http://api.inappsocial.com/Rest1.7/conversation/metadata/get.json?appId=<app-id>
&contentId=<external-content-id>&url=<content-url>

Where;

  • <app_id> is the value of application Id and is mandatory parameter,
  • <content_id> is the unique content identifier,
  • <content_url> is the URL of the content,
  • At least one of the parameters “url” or “contentId” shall be present in the request.

Response:
The response is a JSON object for the Content Metadata and including the following fields;

  • contentId– the external Id of the specific content,
  • url– the Web url of the content,
  • title– the title of the content,
  • author– the author for the content,
  • summary– a summary for the content in text format,
  • createdTime– the time of the content publishing date as a string in the format of “yyyy-MM-dd HH:mm:ss”.
  • mimeType– the mime type of the attached media. Currently it only supports image format of mime type jpeg (mimeType=image/jpeg), png (mimeType=image/png) and gif (mimeType=image/gif)
  • dataSize– the size of the attached media
  • mediaUrl– the link to the actual streamable image
Top of Page