POST buckets

Create a bucket.

Resource Path

/buckets

Request Body

The request body is a JSON representation of the Bucket being created.

Example Request

Below creates a bucket with a single RSS channel.

POST https://api.swiftapp.com/v1/buckets

POST DATA

{
   "name":"New Bucket",
   "public":true,
}

Response

{
	"id": 1235,
	"name": "New Bucket",
	"public": true,
	"drop_count": 0,
	"date_added": "Mon, 20 Jan 2013 13:08:45 +0000",
	"default_layout": "drops",
	"account": {
		"id": 3,
		"account_path": "user3"
	}
}

GET buckets/:id

Returns a Bucket object for the given bucket.

Resource Path

/buckets/:id

Request Parameters

Name	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

GET https://api.swiftapp.com/v1/buckets/1234

Response

{
	"id": 1234,
	"name": "Another Bucket",
	"public": true,
	"drop_count": 100,
	"date_added": "Mon, 07 Jan 2013 13:08:45 +0000",
	"default_layout": "list",
	"account": {
		"id": 3,
		"account_path": "user3"
	}
}

PUT buckets/:id

Modify an existing bucket.

Resource Path

/buckets/:id

Request Body

The request body is a JSON representation of the Bucket being updated.

Example Request

Renames a bucket and modify its public and active statuses.

PUT https://api.swiftapp.com/v1/buckets/1234

PUT DATA

{
   "id":1234,
   "name":"My Bucket Renamed",
   "public":true,
   "active":false,
}

Response

{
   "id":1234,
   "name":"My Bucket Renamed",
   "account_id":"3",
   "follower_count":1,
   "is_owner":true,
   "is_collaborator":false,
   "is_following":false,
   "public":true,
   "drop_count":100,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
}

DELETE buckets/:id

Remove an existing bucket.

Resource Path

/buckets/:id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

DELETE https://api.swiftapp.com/v1/buckets/9999

POST buckets/:id/collaborators

Add a new collaborator to a bucket. Collaborator objects have the following fields:

Field	Type	Read/Write	Description
id	Int64	R	The account id of the collaborator.
read_only	Boolean	RW	True when the account can modify the bucket details, false otherwise
active	Boolean	RW	True when the account has accepted collaboration, false otherwise.
date_added	String	R	Date when the collaborator was added.

Resource Path

/buckets/:id/collaborators

Request Body

The request body is a JSON representation of the Collaborator being added.

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

POST https://api.swiftapp.com/v1/buckets/9999/collaborators

POST DATA

{
   "id":1234,
   "active":false,
   "read_only":false,
}

Response

{
   "id":1234,
   "active":false,
   "read_only":false,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
}

GET buckets/:id/collaborators

Returns a list of collaborators objects of accounts collaborating on the bucket.

Resource Path

/buckets/:id/collaborators

Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

GET https://api.swiftapp.com/v1/buckets/9999/collaborators

Response

[
   {
      "id":1234,
      "active":false,
      "read_only":false,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   },
   {
      "id":4321,
      "active":true,
      "read_only":false,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   }
]

PUT buckets/:id/collaborators/:account_id

Modify a collaborator. This allows the collaboration level to be modified or collaboration to be activated.

Resource Path

/buckets/:id/collaborators/:account_id

Request Body

The request body is a JSON representation of the Collaborator being added.

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
account_id	Required	Account id of the collaborator

Example Request

PUT https://api.swiftapp.com/v1/buckets/9999/collaborators/1234

PUT DATA

{
   "read_only":true,
   "active":true,
}

Response

{
   "id":1234,
   "active":true,
   "read_only":true,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
}

DELETE buckets/:id/collaborators/:account_id

Remove an existing account collaborator. Only bucket owners can perform this action.

Resource Path

/buckets/:id/collaborators/:account_id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
account_id	Required	Account id of the collaborator

Example Request

DELETE https://api.swiftapp.com/v1/buckets/9999/collaborators/345

PUT buckets/:id/followers/:account_id

Add a new follower to a bucket.

Resource Path

/buckets/:id/followers/:account_id

Request Parameters

Field	Type	Description
account_id	Required	The numerical id of the desired bucket

Example Request

PUT https://api.swiftapp.com/v1/buckets/9999/followers/1234

GET buckets/:id/followers

Returns a list of Account objects of accounts following the bucket.

Resource Path

/buckets/:id/followers

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

GET https://api.swiftapp.com/v1/buckets/9999/followers

Response

[
   {
      "id":1234,
      "account_path":"default",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   {
      "id":43211,
      "account_path":"tluafed",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   }
]

DELETE buckets/:id/followers/:account_id

Remove an existing account follower.

Resource Path

/buckets/:id/followers/:account_id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
account_id	Required	Account id of the follower

Example Request

DELETE https://api.swiftapp.com/v1/buckets/9999/followers/345

GET buckets/:id/drops

Returns a list of drops in the bucket.

Resource Path

/buckets/:id/drops

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
count	Optional	Number of drops to return. Default: 50
max_id	Optional	Id that is the pagination reference point. Page numbers are relative to this id.
page	Optional	Page number of results to return relative to max_id.
since_id	Optional	Return count drops with and id greater than this id.
date_from	Optional	Returned drops will have a published date greater than this date
date_to	Optional	Returned drops will have a published date smaller than this date
keywords	Optional	Comma separated list of keywords and phrases. Returned drops will contain these keywords
channels	Optional	Comma separated list of channel names. Returned drops will be from the specified channels
locations	Optional	Comma separated list of bounding boxes. A bounding box is specified by a pair of [longitude,latitude] pairs. Returned drops will contain a place within the bounding box.

Request Headers

Header	Required	Description
X-Stream	Optional	The server will keep the connection open when this field is present and new drops will be written in realtime as they are added to the Bucket.

Example Request

The below request will return 1 Facebook OR Twitter drops with an id less than 999999 AND containing the keywords Kenya OR Uganda AND have a location of San Francisco OR New York City.

GET

Response

[
   {
      "id":1111,
      "channel":"twitter",
      "source_id":"drop's original id",
      "source_url":"http://www.bbc.co.uk/news/business-20943292",
      "title":"drop title",
      "content":"drop content",
      "date_published":"Wed, 27 Aug 2008 13:08:45 +0000",
      "comment_count":0,
      "buckets":null,
      "user_score":0,
      "source":{
         "id":2,
         "name":"identity2_name",
         "username":"identity2",
         "avatar":"http://identity.avatar.com/image.jpg"
      },
      "tags":[
         {
            "tag":"CIA",
            "tag_type":"organization"
         },
         {
            "tag":"A New Tag",
            "tag_type":"thing"
         }
      ],
      "places":[
         {
            "name":"Utopia",
            "type":"point",
            "coordinates":[
               [
                  2.2241006,
                  48.8155414
               ]
            ]
         },
         {
            "name":"China",
            "type":"Polygon",
            "coordinates":[
               [
                  2.2241006,
                  48.8155414
               ],
               [
                  2.4699099,
                  48.8155414
               ],
               [
                  2.4699099,
                  48.9021461
               ],
               [
                  2.2241006,
                  48.9021461
               ]
            ]
         }
      ],
      "links":[
         {
            "url":"http://ushahidi.com/"
         },
         {
            "url":"http://www.bbc.co.uk/sport/0/football/20319573"
         }
      ],
      "media":[
         {
            "url":"http://ushahidi.com/image.jpg",
            "type":"image"
         },
         {
            "url":"http://gigaom2.files.wordpress.com/2012/10/datacapspercentage.mp4",
            "type":"video"
         }
      ]
   }
]

PUT buckets/:id/drops/:drop_id

Add a drop to a bucket.

Resource Path

/buckets/:id/drops/:drop_id

Request Parameters

Field	Type	Description
drop_id	Required	The numerical id of the desired bucket

Example Request

PUT https://api.swiftapp.com/v1/buckets/9999/drops/1111

DELETE buckets/:id/drops/:drop_id

Remove a drop from a Bucket.

Resource Path

/buckets/:id/drops/:drop_id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
drop_id	Required	ID of the drop to be removed from the bucket

Example Request

DELETE https://api.swiftapp.com/v1/buckets/9999/drops/1111

POST buckets/:id/subscriptions

SwiftRiver can push drops to any URL via an HTTP POST or PUT request. This endpoint is used to define such a subscription.

A list of Drops will be published to the given URL at the specified frequency and SwiftRiver will keep trying to publish new drops to the API for 1 hour from when they are produced.

A subscription consists of the target URL, frequency of data transfer and other parameters as shown below:

Field	Type	Read/Write	Required on Create	Description
id	Int64	R		Unique numerical identified for the subscription.
name	String	RW	Y	A user defined label for the subscription.
url	String	RW	Y	The target URL to push drops to.
method	String	RW	Y	"PUT" or "POST". The HTTP Method to use.
frequency	Int	RW	N	Seconds after which to push drops to the defined URL. Minimum: 60 Maximum 900
max_request_size	Int	RW	N	Maximum size in bytes of the request to be posted to the defined URL. Min: 102400 Max: 10485760
verify_ssl_cert	Boolean	RW	N	If url is using HTTPs, verify the certificate used when true.
username	String	RW	N	Username to use with basic authentication at target URL.
password	String	RW	N	Password to use for basic authentication at target URL.
active	Boolean	RW	N	When true, SwiftRiver will attempt to post new drops at the URL otherwise no posting will happen.
date_added	String	R	N	Date when the subscription was added.

Resource Path

/buckets/:id/subscriptions

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Request Body

The request body is a JSON representation of the Subscription being added.

Example Request

POST https://api.swiftapp.com/v1/buckets/9999/subscriptions

POST DATA

{
   "name":"My Cool App",
   "url":"http://example.com/target",
   "method":"post"
}

Response

{
   "id":501,
   "name":"My Cool App",
   "url":"http://example.com/target",
   "method":"post",
   "frequency":60,
   "max_request_size":104857609,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
}

GET buckets/:id/subscriptions

Returns a list of Subscriptions defined in the Bucket by the authenticating user.

Resource Path

/buckets/:id/subscriptions

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket

Example Request

GET https://api.swiftapp.com/v1/buckets/9999/subscriptions

Response

[
   {
      "id":501,
      "name":"My Cool App",
      "url":"http://example.com/target",
      "method":"post",
      "frequency":60,
      "max_request_size":104857609,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   },
   {
      "id":502,
      "name":"My Other Cool App",
      "url":"http://example.com/target2",
      "method":"put",
      "frequency":60,
      "max_request_size":104857609,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   }
]

PUT buckets/:id/subscriptions/:subscription_id

Modify and existing subscription.

Resource Path

/buckets/:id/subscriptions/:subscription_id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket.
subscription_id	Required	The numerical id of the subscription.

Request Body

The request body is a JSON representation of the Subscription being modified.

Example Request

PUT https://api.swiftapp.com/v1/buckets/9999/subscriptions/501

PUT DATA

{
   "name":"My Cool App Renamed",
   "url":"http://example.com/targetRenamed",
   "method":"post"
}

Response

{
   "id":501,
   "name":"My Cool App Renamed",
   "url":"http://example.com/targetRenamed",
   "method":"post",
   "frequency":60,
   "max_request_size":104857609,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
}

DELETE buckets/:id/subscriptions/:subscription_id

Remove a subscription.

Resource Path

/buckets/:id/subscriptions/:subscription_id

Request Parameters

Field	Type	Description
id	Required	The numerical id of the desired bucket
subscription_id	Required	ID of the subscription to be removed.

Example Request

DELETE https://api.swiftapp.com/v1/buckets/9999/subscriptions/1111