Twitter-compatible API
Shout'Em supports Twitter-compatible REST API which lets you use some of existing Twitter clients with Shout'Em. Differences between Shout'Em implementation and the original specification for the Twitter API are given bellow. Original Twitter API documentation can be found at this page. You can see the changelog of the API at this page.
API root URL
Our Twitter-compatible API can be found on the address in the form
http://networkname.shoutem.com/api/twitter/1.0/
where networkname is a name of a Shout'Em network. For example, for 'zrikka' network, API root URL is http://zrikka.shoutem.com/api/twitter/1.0/.
If a network has a custom domain set, it can be used instead of .shoutem.com domain. For example, 'zrikka' network has a custom domain zrikka.com and the API can be found at http://zrikka.com/api/twitter/1.0/ also.
Note: we have recently mounted Twitter-compatible API to one more location. That is
http://networkname.shoutem.com/api/
this one is added to enable clients that support Laconica/Identica style API URL. It will always point to the most recent version of the API. However, since Twitter is known to change it's API often, and sometimes by breaking the compatibility with previous versions, it is advisable to use the URL with the version information whenever possible (to avoid possible compatibility issues).
Authentication
We use standard HTTP-basic authentication. We accept both - member's e-mail or his network nickname as the username.
OAuth support will come soon.
Rate limiting
Currently, we don't impose any rate limit. However, we'll add this feature in the future.
Parameters
Callback parameter
We don't support JSONP callback parameter at the moment, but we will implement this feature very soon.
Suppress response codes parameter
We don't currently support suppress_response_codes parameter.
If-Modified-Since
If-Modified-Since request header is supported as described in the Twitter documentation.
Method differences
General notes
- Twitter uses integers for user and status IDs. Shout'Em uses integers for status IDs, and Universally unique identifiers (UUIDs) as user IDs. UUIDs are base64 encoded as strings, and should be opaque (with no meaning) to the caller.
- Using since_id parameter will give correct results only if the status or user with that ID really exists. This is slightly different than current Twitter implementation and will be change in the future to fit better with the Twitter API.
- We have introduced a non-standard include_shoutem_fields parameter. If this parameter is set to true, Shout'Em will add some Shout'Em specific fields (like attachment URL) to the method response.
- For all entities, ID's begin with 1. However, 0 is used in some special cases, i.e. creator_id for places common to all ShoutEm networks.
- Status types:
| Type (literal) |
Type description |
| avatar_update |
|
| badge_unlocked |
User (actor) received (unlocked) a new badge. Badges are currently the same system wide, i.e. on all networks. |
| check_in |
User (actor) checked in to a selected place. |
| event_attending |
|
| new_friendship |
|
| new_mayor |
User (actor) became chief of a place. NOTE: Type literal will soon change to "new_chief". |
| new_place |
|
| new_subscription |
User (actor) starts following (subscribes) a selected user (target). |
| system |
|
| profile_update |
|
| status_update |
Plain old status update. |
Status methods
✔ statuses/public_timeline.format [link]
Shout'Em currently doesn't cache the result of this method (as the Twitter does for it's public timeline). It will always return the most recent status list.
✔ statuses/friends_timeline.format [link]
✔ statuses/home_timeline.format
✔ statuses/user_timeline.format [link]
✔ statuses/show/id.format [link]
✔ statuses/update.format [link]
If you provide in_reply_to_status_id parameter to this method, and the status with that id doesn't exist, we will add the new status as if this parameter was not provided.
✔ statuses/destroy/id.format [link]
User methods
✔ users/show/id.format
✔ statuses/friends.format [link]
✔ statuses/followers.format [link]
Direct message methods
✔ direct_messages.format
✔ direct_messages/sent.format
✔ direct_messages/destroy/id.format
Friendship methods
✔ friendships/create/id.format
Creates a subscription (starts following) to a given user.
Method(s): POST
Parameters:
user_id The ID of the user to subscribe to. Required.
Returns: Befriended user if successful, error information string otherwise.
✔ friendships/destroy/id.format
Destroys a subscription (stops following) to a given user.
Method(s): POST
Parameters:
user_id The ID of the user to cancel subscription to. Required.
Returns: Unfriended user if successful, error information string otherwise.
✔ friendships/exists.format
Tests existence of friendship between two users.
Method(s): GET
Parameters:
user_a The ID of the first user to test friendship for. Required.
user_b The ID of the second user to test friendship for. Required.
Returns: true if friendship exists, false otherwise
✔ friendships/show.format
Shows details about subscription relation between two users.
Method(s): GET
Parameters:
source_id The ID of the source user in the subscription relation. Required.
target_id The ID of the target user in the subscription relation. Required.
Returns: Relationship object
Social graph methods
✔ friends/ids.format
✔ followers/ids.format
Account methods
✔ account/verify_credentials.format
✔ account/end_session.format
✔ account/update_location.format
✘ account/update_delivery_device.format
Not implemented yet.
✔ account/update_profile_colors.format
Shout'Em doesn't support different colors for the sidebar fill and border. Therefore profile_sidebar_fill_color and profile_sidebar_border_color parameters are ignored in a call to this method.
✔ account/update_profile_image.format
✔ account/update_profile_background_image.format
✔ account/update_profile.format
Shout'Em currently does not support email change. That's the reason why email parameter is currently ignored.
✔ account/rate_limit_status.format
Currently we don't throttle API requests. This method just returns default data always.
Favorite methods
✔ favorites.format
✔ favorites/create/id.format
✔ favorites/destroy/id.format
Notification methods
✔ notifications/follow/id.format
✔ notifications/leave/id.format
Block methods
✔ blocks/create/id.format
✔ blocks/destroy/id.format
Help methods
✔ help/test.format
Search methods
✔ search.format
Network methods
✔ networks/show/id.format
Returns information about a ShoutEm network, specified by the network ID. Authentication is not required.
Method(s): GET
Parameters:
id The ID of the requested network. Required.
✔ networks/search.format
Returns a set of ShoutEm networks which contain the given term in either the network name or network subdomain parameters.
Method(s): GET
Parameters:
term Search term. Required.
count Maximum number of networks in the request response. Default value: 20. Optional.
page Response page number. Default value: 0. Optional.
[COMING SOON]
Place methods
Note: return format of all methods can be either "xml" or "json".
places/show/id.format
Returns information about a place, specified by ID. You must be properly authenticated to request the place info of a private network, otherwise no authentication is required.
Method(s): GET
Parameters:
id Required. The ID of the requested place.
places/new.format
Creates a new place entry. You must be properly authenticated to create a place.
Method(s): POST
Parameters:
longitude Required. The longitude of place's position.
latitude Required. The latitude of place's position.
name Required. The place's name.
address Optional. The place's address, defaults to empty string.
city Optional. The place's city, defaults to empty string.
country Optional. The place's country, defaults to empty string.
places/update/id.format
Updates a place entry. You must be properly authorized to update a place: either own that place or be one network's admins or moderators.
Method(s): POST
Parameters:
id Required. The place's id.
longitude Optional. The longitude of place's position.
latitude Optional. The latitude of place's position.
name Optional. The place's name.
address Optional. The place's address.
city Optional. The place's city.
country Optional. The place's country.
places/destroy/id.format
Deletes a place entry. You must be properly authorized to update a place: either own that place or be one network's admins or moderators.
Method(s): POST, DELETE
Parameters:
id Required. The place's id.
places/nearby.format
Returns a list of found nearby places. Paging is optional. You must be properly authenticated to request the places info of a private network, otherwise no authentication is required.
Method(s): GET
Parameters:
longitude Required. The longitude of the point that the distance is calculated from.
latitude Required. The latitude of the point that the distance is calculated from.
radius Optional. Radius in meters, defaults to 1 km.
page Optional. The current page, defaults to 0.
count Optional. The page size, defaults to 20 and won't exceed 200.
include_users Optional. The flag that instructs to embed user list for each respective place.
IMPORTANT NOTES ABOUT PLACES API:
- For places common to all ShoutEm networks, creator_id parameter is set to 0. Since 0 is not a valid entity id in ShoutEm, it should be properly handled.
Status methods
statuses/at_place/id.format
Returns a list of shouts shouted at pointed place. Paging is optional. You must be properly authorized to request the shouts of a private network, otherwise no authentication is required.
Formats: xml, json, rss, atom
Method(s): GET
Parameters:
id Required. The ID of the place the search is done for.
page Optional. The current page, defaults to 0.
count Optional. The page size, defaults to 20 and won't exceed 200.
include_shoutem_fields
User methods
users/at_place/id.format
Returns a list of members checked in at pointed place. You must be properly authorized to request the members of a private network, otherwise no authentication is required.
Formats: xml, json
Method(s): GET
Parameters:
id Required. The ID of the place the search is done for.
include_shoutem_fields
Examples
Typical JSON result for a "statuses/show/id.format?include_shoutem_fields=true" call:
{
"id": 1697902,
"text": "Hi all! Testing 'Places' feature... ;)",
remaining status fields...
"shoutem_place": {
"id": 2,
"creator_id": 8,
remaining place fields...
}
}
Typical JSON result for a "places/show/id.format" call:
{
"id": 2,
"creator_id": 8,
"created_at": "Fri Nov 13 19:47:14 +0000 2009",
"geo": {
"type": "Point",
"coordinates": [45.79453, 15.92808]
},
"name": "Place name",
"address": "Place address 123",
"city": "Place City",
"country": "Place Country"
}
Note: The geo field is the same as in a status object.
If the call to an action returns multiple results, they will all be nested in an array object.
Comments (0)
You don't have permission to comment on this page.