API

From SocialStrap Wiki
Jump to: navigation, search


Introduction

SocialStrap's API (application programming interface) is a powerful tool that allows developers to build and connect various mobile and desktop applications to a SocialStrap powered websites. This native API has been introduced in SocialStrap since version v4.2.

API sits on every page, listen to requests and responds by outputting JSON formatted data. Available data set depends on requested URL but you will normally get JSON-packed data for the corresponding page that you can see in your browser on this URL. For example, if you call the API on specific user profile URL you will receive all user-related data as well as posts on his timeline, all the metadata and other related variables. You may also receive form descriptions and other variables that are not visible in standard html output. Technically, this API can only be used to retrieve data from the server, for writing data and posting to the server use the standard GET/POST requests.

Example JSON output:

...
	"feed_offset": "4716",
	"posts_data": [{
		"user_screen_name": "user1",
		"author_id": "124",
		"post_wall_id": "124",
		"post_wall_name": "user1",
		"post_wall_screen_name": "user1",
		"post_wall_avatar": "e632ccaedabfd782493b324828068fbdfc040ff2.jpg",
		"post_wall_profile_type": "user",
		"post_wall_profile_owner": "0",
		"user_name": "user1",
		"user_avatar": "e632ccaedabfd782493b324828068fbdfc040ff2.jpg",
		"post_id": "4726",
		"post_content": "SocialStrap is celebrating its first birthday by offering 50% discount today! Thank you all again for an amazing first year! ",
		"post_created_on": "2015-01-09 12:06:10",
		"post_privacy": "public",
		"rich_content_json": null,
		"is_reported": 0,
		"post_images": [{
			"image_id": "2042",
			"file_name": "3cc96479acdceb781760d9d08a6ed9c94734e228.png",
			"size": "35331"
		}],
		"likes_count": 0,
		"is_liked": 0,
		"author_meta": {
			"background_file": "715bc05318f740b4fdc3d44073df40a029788731.jpg",
			"background_noimage": "0",
			"background_repeat": "1",
			"background_scroll": "1",
			"background_stretch": "1",
			"badges": "user,leaf,ok-sign",
			"big_avatar": "a8ed8107f539274040f7557c80db0592404ae7f5.jpg",
			"birthday": "1980-06-06 00:00:00",
			"contact_privacy": "e",
			"description": "",
			"gender": "male",
			"location": "",
			"show_online_status": "s",
			"website": "http:\/\/example.com"

...


API settings

To enable API feature, login as admin and go to Settings -> API. Here you can set your API request key (apikey) which will be used in 3rd party applications to switch the API output on. Developers can send "apikey" variable in both ways POST and GET. For example, you can call the API by simply attaching "apikey" at the end of the URL like this: yoursite.com/somepage?apikey=1234567


Inspecting JSON output with Chrome

When working with JSON output I find Chrome's page inspector very useful. With this (or similar) tool you can quickly see what data and format is available at specific page URL.

Chrome api.jpg



Login and security

When user is logged in using the "apikey", application will return user identity in JSON format. To login user and authenticate with the website use the standard POST form submit (form#Login). When logged in, API will respect all the filtering and security as you would normally see on the website. Warning: API can return more data than you would normally see on the website. For example, API can return group owner ID which you cannot normally see. To filter such data use custom addons (see below).


Modifying data and/or runtime config

Sometimes you may need to modify specific runtime configuration like perhaps how many posts to display per page. There is a sample addon called 'API Config' that shows how to modify SocialStrap's runtime configuration and filter API output variables. You can download this addon from here: http://www.socialstrap.net/addons


Pagination and post feed offsets

When paginating through simple paginated pages (ex. yoursite.com/notifications/list) use the simple URL pattern with page/n parameter attached at the end. Example: yoursite.com/notifications/list/page/3

To paginate on pages with infinite scroll use the following pattern:

first page https://live.socialstrap.net/alcalbg (API responds with feed_offset=6030) next page = https://live.socialstrap.net/alcalbg/?feed_offset=6030 (API responds with new feed_offset=5872) next page = https://live.socialstrap.net/alcalbg/?feed_offset=5872 and so on...


Forms

When URL endpoint contains one or more forms they will be returned as JSON data too with. Variable called "identifier" will contain all attributes so you can automatically create forms in your application.

Example form JSON data:

	"add_post_form": {
		"show_privacy": true,
		"translator": {
			
		},
		"formname": "AddPost",
		"identifier": {
			"helper": "formHidden",
			"action": "",
			"content": {
				"type": "Zend_Form_Element_Textarea",
				"id": "content",
				"name": "content",
				"value": "",
				"label": null,
				"attribs": {
					"COLS": "",
					"ROWS": "4",
					"class": "form-control",
					"placeholder": "What is on your mind?"
				},
				"messages": [],
				"errorMessages": [],
				"errors": []
			},
			"submitbutton": {
				"type": "Zend_Form_Element_Submit",
				"id": "submitbutton",
				"name": "submitbutton",
				"value": null,
				"label": "Post",
				"attribs": {
					"class": "submit btn btn-default"
				},
				"messages": [],
				"errorMessages": [],
				"errors": []
			}
		},
		"csrf": null
	},


Languages

You can get all translation strings and see available languages at usual endpoint yoursite.com/index/language?apikey=1234567


Example JSON response:

{
	"list": {
		"en": "en"
	},
	"current": {
		"Disable CSRF protection on forms": "Disable CSRF protection on forms",
		"Enable API endpoint": "Enable API endpoint",
		"Warning: Opening API endpoint can potentially make your data less secure.": "Warning: Opening API endpoint can potentially make your data less secure.",
		"Open": "Open",
		"Close": "Close",
		"More": "More",
		"Less": "Less",
...