/data/signals

hide

Back to ReST API Resources map.
Back to Socialtext REST Documentation.

Up: /data
Children: /data/signals/hash_or_id , /data/signals/:idlist/visible , /data/signals/:idlist/!visible

Contents


A collection presenting a list of signals visible to the user.

Example:
http://www.socialtext.net/data/signals?limit=10

Supported operations:

GET

GET-

Filtering GET

You may filter GET /data/signals in the following ways:

using q=searchterm

A parameter "q=searchterm" will perform a full text search on Signals:

  • limit/count and offset perform as described offset and limit query parameters.
  • &order=<relevance|date|sender> : determines the sort order of the results.
  • &direction=<asc|desc>`: determines the direction of the sort, ascending or descending.

other parameters

  • following=1 : Filter the list to include only signals from people the caller is following.
  • after=timestamp : Filter list to include only signals after a certain date-time. The timestamp example: 2010-07-23 16:26:28.631567Z
  • before=timestamp : Filter list to include only signals before a certain date-time. The timestamp as above.
  • direct=<both|sent|received> : Filter the list to include direct messages (i.e. private Signals). This parameter can have the value `both, sent, or received. The default is that no direct messages are included in the GET response.
  • sender=<id |username> : Filter the list to include signals sent by a single person. This parameter has the value of a user's id (numeric) or username.
    • If sender is a user the viewer can't see, returns a 403 Forbidden status code.
    • If sender and followed parameters are both used, followed is ignored.
    • If sender and direct parameters are used, and sender is not the viewer, then it returns a 403 Forbidden status code.
    • If sender and direct=<sent or both> parameters are used, and sender and the viewer are the same, this returns sent direct messages and user's signals.
    • If sender and direct=received parameters are given, and sender and the viewer are the same, this returns user's signals, no direct messages.
  • hidden=1 : Causes GET to include signals that have been 'hidden' but have not yet been deleted.
  • direction=<asc|desc> : sort the Signals in either ascending or descending order by date.
  • groups=id : Filter the list to include signals visible to the specified group.
    • The groups parameter supports a comma delimited list of groups, e.g. groups=1,2,3.
    • Groups where the viewer is not a member of are ignored.
  • accounts=id : Filter the list to include Signals visible to the specified account.
    • The accounts parameter supports a comma delimited list of accounts, e.g. accounts=1,2,3.
    • Accounts the viewer is not a member of are ignored.

POST

POST -

  • Create a new signal for the caller.
  • You will get a 403 if you attempt to send a direct message to a user whose profile you cannot 'see'.
  • This call returns 4 informational headers:
    • Location the canonical user-visible URI of this signal (e.g. /st/signals/:hash)
    • X-Location the machine-readable "data" URI of this signal (i.e. /data/signals/:hash)
    • X-Signal-ID the ID number of this signal
    • X-Signal-Hash the permalink hash of this Signal
  • Of interest, you may post any of the following:
    • an annotations hash within your Signal.
    • an attachment to a Signal. You must first upload the Signal. When a signal is being sent, the client includes in an attachments argument with the ID-hash strings. This file then becomes permanently attached to the Signal, and the temporary uploaded file is deleted.
  • Representations

DELETE

    • To permanently remove a signal (not just hide) from the system
    • Can only be called by a user that has business_admin role

Using /data/signals

See the following pages for more information on /data/signal usage.

Code Sample

The following code snippet demonstrates a simple POST in python:

#!/usr/bin/python
import urllib2
import simplejson 

# simplejson is external lib for python 2.5 and earlier
# just use builtin lib json in python2.6+ 

username = "someuser@somedomain.com"
password = "somepass"

# create a password manager
password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()

# Add the username and password.
# If we knew the realm, we could use it instead of ``None``.
top_level_url = "http://dev7.socialtext.net"
password_mgr.add_password(None, top_level_url, username, password)

handler = urllib2.HTTPBasicAuthHandler(password_mgr)
opener = urllib2.build_opener(handler)

urllib2.install_opener(opener)

##### INTERESTING STUFF

headers = {'content-type':'application/json'}
response = urllib2.urlopen('http://dev7.socialtext.net/data/peopletags/smart')
taggedusers=simplejson.loads(response.read())

headers = {'content-type':'text/x.socialtext-wiki'}

data = '^^ Users tagged with "smart"\n\n'

for user in taggedusers:
    print user['best_full_name'] + " is smart!"
    data = data + "* {user: "+user['id']+"}\n"

req = 
   urllib2.Request(
     'http://dev7.socialtext.net/data/workspaces/foobar/pages/smartpeople?http_method=put',
      data, headers)

try:
    response = urllib2.urlopen(req)
except urllib2.HTTPError, e:
    if e.code >= 200 and e.code < 300: 
        print "Updated list of users"

Version information

Updates: (newest at the top)

  • APIv25
    • You may use query strings to look for tags.
  • APIv24 :
    • POST /data/signals now returns 4 informational headers - Location, X-Location, X-Signal-ID, and `X-Signal-Hash.
    • POST /data/signals allows attachments.
  • APIv23
    • GET /data/signals and /data/signals?filter= includes annotations .
    • POST /data/signals accepts annotations hash.
  • APIv21
    • Filter the list to include signals visible to certain groups with the groups=id parameter.
    • Filter the list to include signals visible to certain accounts with the accounts=id parameter;
  • APIv13
    • direction=asc and direction=desc can be used with /data/signals, not just for queries.
  • APIv12
    • q=searchterm functionality added.
  • APIv10 :
    • DELETE operation added.
    • hidden=1 functionality added.
  • APIv7 :
    • Filter the list to include Signals sent by a single person with the sender parameter.

Back to ReST API Resources map.
Back to Socialtext REST Documentation.


Click this button to save this page to your computer for offline use. Created by Shawn Devlin on Jan 6 4:25pm. Updated by Brandon Noard on Jul 27 10:04am. (27 revisions, 1,454 views)