Documentation

Introduction

What is this?

Postcard has been built around the fundamental idea of standardizing the way we use social media. The iOS app was created with several key functions that accomplish this goal:

It's a social media authoring tool that gives you post-by-post control of where you share the message
It allows any prepared website to also receive the posted content
It lets one network serve as a 'host' and the remaining networks share a link back to that 'host' network's content

Why use it?

The Postcard iOS app takes a heavy focus on the authoring experience and fast sharing to multiple network simultaneously. If you enjoy sharing similar links, pictures and other content to your favorite networks such as Twitter, Facebook, LinkedIn and Tumblr, you will love the time saved by getting it all done at once.
If you are a website owner or content creator, the app also offers a 'Custom Network' functionality that allows any web server to receive content by adhering to the Postcard API Protocol. Better yet, there is already a plugin available for WordPress that makes it an easy install for most website owners. With this power users are free to display and distribute content however they please. You're free to run your own personal social network.
Postcard also introduces the idea of hosting content. By setting a network as the host when posting messages, it will be used as the link for sharing to all subsequent networks. This gives users the ability to direct traffic where they want. Either from their website to social networks or from one social network to another. Content creators should recognize the potential of this tool to help direct traffic places that are most important to them i.e. websites with other content, items for sale or advertising

Creating your own network

If you don't use WordPress for as your website framework, you can still create a functional API that communicates with the iOS app in any language. By following the API Protocol documented below, your website can respond appropriately to content shared with it and be stored however you like.

The Postcard Plugin for WordPress is intended to serve as an example of how one could implement this documented API protocol. You should review it's code base for deeper hints at how you can store and display social content using this API protocol.

The Postcard API Protocol

By implementing the following protocol in your own web service, you can communicate with the Postcard app for iOS.

Make sure to pay close attention to the expected responses from each api call as this is a fundamental part of getting the app and server to communicate nicely.

Endpoint format

In order to be the most accommodating API, the Postcard app has been designed to work with 2 acceptable API formats: URL Path and Query string. For example, the Wordpress plugin functions around the query string style so that permalink format never compromises access.

Example use case

Let's say out website URL is "http://www.mywebsite.com/" and we want to hit the "post/add_with_media" endpoint to submit a photo. Both would be acceptable formats:

URL Path style:

http://www.mywebsite.com/post/add_with_media

Query String Style:

http://www.mywebsite.com?postcard_api=true&endpoint=post/add_with_media

Note: postcard_api and endpoint are required GET parameters. Only postcard_api is needed to add your website as a network though

When you first add your website to Postcard for iOS, it will scan your URL and look for the existence of the postcard_api in the query string. It will then accordingly use the format found in all subsequent calls made.

Authorization

Every POST call to the API require an auth token (except initial authorization), while GET calls are openly available. For convenience, each endpoint also indicates whether auth is required or not.

You can get an auth token from the server by using the /authenticate call. The returned token should be stored safely and attached with the token parameter in future API calls.

Note: token should be a POST parameter

API Endpoints

/authenticate

Method

POST

Requires Auth Token?

Required Fields

username, password

Description

Authorizes a tool to use the postcard api. Returns a long lived auth token for creating postcard content. This token must be provided with most other calls.

Expected Response Format

{ "success": true, "payload": { "token": "02230cbfbe21618451ba11a77293642e11418ee182a423c1e6ee0ad0c0ce507b" }, "message": "successful authentication" }

/post/add

Method

POST

Requires Auth Token?

Yes

Required Fields

date, message

Optional Fields

tags, url

Description

Create a new text post message

Expected Response Format

{ "success": true, "payload": { "user_id": "1", "date": "2014-01-01 08:00:00", "message": "Hello World!", "id": 157, "permalink": "http://www.mywebsite.com/?page_id=4&pc_id=157" }, "message": "Successfully added postcard" }

/post/add_with_media

Method

POST

Requires Auth Token?

Yes

Required Fields

date, message, image

Optional Fields

tags, url, video

Description

Create a new post message with rich media content. Image is always required either as the main content or the placeholder image to video.

If it is a video post, the image should be the same dimensions as the video.

Expected Response Format

{ "success": true, "payload": { "user_id": "1", "date": "2014-01-01 08:00:00", "message": "Hello World!", "image": "http://www.mywebsite.com/wp-content/uploads/2014/01/screenshot-22.png", "width": 640, "height": 1136, "video": "http://www.mywebsite.com/wp-content/uploads/2014/01/17A5A575-4E67-4A5B-84B8-205E78CFB38E-1375-00000119518D47FB_1.1.mp4", "id": 158, "permalink": "http://www.mywebsite.com?page_id=4&pc_id=158" }, "message": "Successfully added postcard" }

/post/delete

Method

DELETE

Requires Auth Token?

Yes

Required Fields

Description

Delete posts. You must be the original poster in order to delete a post.

Expected Response Format

{ "success": true, "payload": null, "message": "Success deleting postcard" }

/post/get

Method

GET

Requires Auth Token?

Required Fields

Description

Get a single post by ID

Expected Response Format

{ "success": true, "payload": { "id": "157", "user_id": "1", "date": "2014-01-01 08:00:00", "message": "Hello World!", "url": null, "image": null, "video": null, "width": null, "height": null, "user": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2014/01/2014-01-01-160x160.jpg" } }, "message": "Success getting postcard" }

/post/search

Method

GET

Requires Auth Token?

Optional Fields

user_id, before, since, url, tags, image, video, count

Description

Search the database of post content by many possible parameters

Expected Response Format

{ "success": true, "payload": [ { "id": "157", "user_id": "1", "date": "2014-01-01 08:00:00", "message": "Hello World!", "url": null, "image": null, "video": null, "width": null, "height": null, "user": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2013/09/2013-09-29-150651-160x160.jpg" } }, { "id": "156", "user_id": "1", "date": "2014-01-25 16:39:01", "message": "#love ", "url": null, "image": null, "video": null, "width": null, "height": null, "user": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2013/09/2013-09-29-150651-160x160.jpg" } }, { "id": "154", "user_id": "1", "date": "2014-01-25 15:48:55", "message": "Resetting ", "url": null, "image": "http://www.website.com/wp-content/uploads/2014/01/2014-01-25-154855.jpg", "video": null, "width": "540", "height": "720", "user": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2013/09/2013-09-29-150651-160x160.jpg" }, "thumbnail": "http://www.website.com/wp-content/uploads/2014/01/2014-01-25-154855-160x160.jpg" }, { "id": "153", "user_id": "1", "date": "2013-12-28 00:04:29", "message": "E", "url": null, "image": "http://www.website.com/wp-content/uploads/2013/12/2013-12-28-000429.jpg", "video": null, "width": "540", "height": "720", "user": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2013/09/2013-09-29-150651-160x160.jpg" }, "thumbnail": "http://www.website.com/wp-content/uploads/2013/12/2013-12-28-000429-160x160.jpg" } ], "message": "Postcard search complete" }

/status

Method

GET

Requires Auth Token?

Description

A simple call to determine server status

Expected Response Format

{ "success": true, "payload": { "url": "http://www.mywebsite.com", "title": "My awesome custom network", "description": "This network is the coolest" }, "message": "Welcome to the Postcard API" }

/user/get

Method

GET

Requires Auth Token?

Required Fields

Description

Gets a single piece of user info by ID

Expected Response Format

{ "success": true, "payload": { "id": "1", "username": "kylnew", "display_name": "kylnew", "picture": "http://www.website.com/wp-content/uploads/2013/09/2013-09-29-160x160.jpg" }, "message": "Postcard user found" }

/user/picture

Method

GET

Requires Auth Token?

Required Fields

Description

Get a redirect link to the user's profile picture

Expected Response Format

302 Redirect http://www.website.com/wp-content/uploads/2013/09/2013-09-29-160x160.jpg