SpeakCoding API

Table of Contents

• Authentication
• Requests
  • Create User
  • Authenticate User
  • Forget User’s authentication token
  • Update User
  • Show User
  • Follow User
  • Unfollow User
  • Search Users
  • List followers
  • List followees
  • Create Post
  • Update Post
  • Destroy Post
  • List Posts
  • Get What’s new feed
  • List Posts of a user
  • Like Post
  • Unlike Post
  • List Post likers
  • Save Post
  • Unsave Post
  • List saved posts
  • List posts where specific user where tagged
  • Create comment
  • Update comment
  • Delete comment
• Data types
  • User
  • Post
  • Comment
  • Like
  • Tag

SpeakCoding Instagram API conforms to JSON:API standard.

Authentication

Clients get authentication token in response to Create User and Authenticate User requests. They MUST include this token with all requests to the API by using Authentication-Token header.

Requests

Create User

POST /users.json

Client MUST NOT be authenticated.

Parameters: all User data type parameters and additional password parameter for password. Namespaced with user.

Response

User structure. Meta contains authentication_token to use for authentication.

Authenticate User

POST /users/authenticate.json

Client MUST NOT be authenticated.

Parameters: user[email] and user[password].

Response

Same as for [Create user], but for given user.

Forget User’s authentication token

POST /users/forget.json

Client MUST be authenticated.

Response

Blank object {}.

Update User

PUT /users/:id.json

Client MUST be authenticated and can only update it’s own user.

Parameters: all User data type parameters.

Response

Updated User structure.

Show User

GET /users/:id.json

Client COULD use me as :id to show current user.

Response

User structure.

Follow User

POST /users/:id/follow.json

Client MUST be authenticated and MUST NOT follow itself.

Response

Updated User structure of a followee.

Unfollow User

POST /users/:id/unfollow.json

Client MUST be authenticated and MUST NOT unfollow itself.

Response

Updated User structure of an unfollowee.

Search Users

GET /users/search.json

Parameters: query (search query).

Response

List of User structures. Top 10 search results.

List followers

GET /users/:id/followers.json

Client MUST be authenticated.

Response

List of User structures of a followers.

List followees

GET /users/:id/followees.json

Client MUST be authenticated.

Response

List of User structures of a followees.

Create Post

POST /posts.json

Client MUST be authenticated.

Parameters: Post data type parameters namespaced with post.

Response

Post structure.

Update Post

PUT /posts/:id.json

Client MUST be authenticated.

Parameters: Post data type parameters namespaced with post.

Response

Post structure.

Destroy Post

DELETE /posts/:id.json

Client MUST be authenticated.

Response

Post structure of recently deleted post.

List Posts

GET /posts.json

Response

List of Post structures.

Get What’s new feed

GET /users/:id/whats_new.json

Response

List of Like structures.

List Posts of a user

GET /users/:user_id/posts.json

Response

List of Post structures.

Like Post

POST /posts/:id/like.json

Client MUST be authenticated.

Response

Updated Post structure.

Unlike Post

POST /posts/:id/unlike.json

Client MUST be authenticated.

Response

Updated Post structure.

List Post likers

GET /posts/:id/likers.json

Response

List of <User>> structures.

Save Post

POST /posts/:id/save.json

Client MUST be authenticated.

Response

Updated Post structure.

Unsave Post

POST /posts/:id/unsave.json

Client MUST be authenticated.

Response

Updated Post structure.

List saved posts

GET /posts/saved.json

Response

List of Post structures.

List posts where specific user where tagged

GET /posts/tagged.json

Client MUST be authenticated.

Parameters:

Attribute name	Type	Description
user_id	Integer?	ID of tagged user. If not provided, current user will be picked.

Response

List of Post structures.

Create comment

POST /comments.json

Client MUST be authenticated.

Parameters:

Attribute name	Type	Description
comment[post_id]	Integer	Post ID
comment[text]	String	Comment text

Response

New Comment structure.

Update comment

PUT /comments/:id.json

Client MUST be authenticated.

Parameters:

Attribute name	Type	Description
comment[text]	String	Comment text

Response

Updated Comment structure.

Delete comment

Delete /comments/:id.json

Client MUST be authenticated.

Response

Deleted Comment structure (state before deletion).

Data types

User

Attribute name	Type	Description
id	Integer	Identificator of a user
email	String	Email address
user_name	String?	User name
bio	String?	Biography
profile_picture	String	Userpic URL
posts_count	Integer	Total number of user’s posts
followers_count	Integer	Total number of user’s followers
followees_count	Integer	Total number of user’s followees
is_follower	Boolean	Is this user a follower of the current user?
is_followee	Boolean	Is this user a followee of the current user?

Post

Attribute name	Type	Description
id	Integer	Identificator of a post
location	String?	Location (example: "New York Central Park")
caption	String?	First post comment of post creator
image	String	Post image URL
user	User	Creator of post structure
likes_count	Integer	Total number of likes for this post
liked	Boolean	Was this post liked by current user?
liker_followee	User	Followee of a current user that liked this post
saved	Boolean	Was this post saved by current user?
created_at	Integer	UNIX timestamp of Post creation
tags	Array of Tag structures	Tags of people on the photo
comments	Array of Comment structures	Ordered array of post comments

Comment

Attribute name	Type	Description
id	Integer	Comment ID
user	User	Comment creator
text	String	Comment text
created_at	Integer	UNIX timestamp of Comment creation

Like

Attribute name	Type	Description
user	User	Liker user
post	Post	Liked post
created_at	Integer

Tag

Attribute name	Type	Description
user	User	Tagged user
top	Float	Tag offfset from top (0.0..1.0)
left	Float	Tag offfset from left (0.0..1.0)