POST drops

Create a drop.

Resource Path

/drops

Request body structure

The request body is a JSON representation of the Drop being created. Pass an array of Drop objects to create multiple drops at once.

Example Request

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

POST DATA

[
    {
        "title":"At this point in time, Kenyan businesses & start ups must make strong headway for the Nigerian market. Ask Blackberry.",
        "content":"At this point in time, Kenyan businesses & start ups must make strong headway for the Nigerian market. Ask Blackberry.",
        "date_published":"Wed, 27 Aug 2008 13:08:45 +0000",
        "channel":"twitter",
        "channel_ids": [45, 22],
        "original_id":"288898001374674946",
        "original_url":"https://twitter.com/matrixster/status/288898001374674946",
        "rivers":[99, 323, 105],
        "source":{
            "name":"Matrix",
            "username":"matrixster",
            "avatar":"https://twimg0-a.akamaihd.net/profile_images/1850198787/helmet_bigger_normal.jpg",
            "origin_id": 18671386
        },
        "tags":[
            {
                "tag":"BlackBerry",
                "type":"organization"
            },
            {
                "tag":"A New Tag",
                "type":"thing"
            }
        ],
        "places":[
            {
                "name":"Kenya",
                "type":"point",
                "longitude": 37.96875,
                "latitude": -0.703107
            }
        ]
    }
]

Response

[
    {
        "id":724893,
        "channel":"twitter",
        "original_id":"288898001374674946",
        "original_url":"https://twitter.com/matrixster/status/288898001374674946",
        "title": "At this point in time, Kenyan businesses & start ups must make strong headway for the Nigerian market. Ask Blackberry.",
        "content": "At this point in time, Kenyan businesses & start ups must make strong headway for the Nigerian market. Ask Blackberry.",
        "date_published":"Wed, 27 Aug 2008 13:08:45 +0000",
		"user_score":0,
        "comment_count":0,
		"image":"",
		"buckets":[],
		"read":false,
        "source":{
            "id:": 18671386,
            "name":"Matrix",
            "username":"matrixster",
            "avatar":"https://twimg0-a.akamaihd.net/profile_images/1850198787/helmet_bigger_normal.jpg"
        },
        "tags":[
            {
                "tag":"BlackBerry",
                "tag_type":"organization"
            },
            {
            "tag":"A New Tag",
            "tag_type":"thing"
            }
        ],
        "places":[
            {
                "name":"Kenya",
                "type":"point",
                "longitude":37.96875,
                "latitude":-0.703107
            }
        ],
		"links":[],
		"media":[],
		"forms":[]
    }
]

POST (rivers or buckets)/:id/drops/:drop_id/comments

Add a comment to a drop in a river or a bucket.

Resource Path

rivers/:id/drops/:drop_id/comments
buckets/:id/drops/:drop_id/comments

Request parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.

Request body structure

The request body is a JSON representation of the Comment.

Example Request

POST https://api.swiftapp.com/v1/rivers/9/drops/1234/comments

POST DATA

{
   "comment_text":"This is spam.",
   "account":{
      "id":1234,
      "name":"Joe Smith",
      "account_path":"default",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true
   }
}

Response

{
   "id":573,
   "comment_text":"This is spam.",
   "deleted":false,
   "date_added":"Wed, 27 Aug 2008 13:08:45 +0000",
   "account":{
      "id":1234,
      "name":"Joe Smith",
      "account_path":"default",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true
   }
}

GET (rivers or buckets)/:id/drops/:drop_id/comments

Returns a list of Comment objects in the specified drops.

Resource Path

rivers/:id/drops/:drop_id/comments
buckets/:id/drops/:drop_id/comments

Parameters

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

Example Request

GET https://api.swiftapp.com/v1/rivers/9/drops/1234/comments

Response

[
   {
      "id":573,
      "comment_text":"This looks like spam.",
      "deleted":false,
      "date_added":"Wed, 27 Aug 2008 13:08:45 +0000",
      "account":{
         "id":1234,
         "name":"Joe Smith",
         "account_path":"default",
         "subscriber_count":10,
         "subscribed_count":99,
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true
      }
   },
   {
      "id":574,
      "deleted":true,
      "date_added":"Wed, 27 Aug 2008 13:08:45 +0000",
      "account":{
         "id":1234,
         "name":"Joe Smith",
         "account_path":"default",
         "subscriber_count":10,
         "subscribed_count":99,
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true
      }
   }
]

DELETE (rivers or buckets)/:id/drops/:drop_id/comments/:comment_id

Delete an existing comment.

Resource Path

rivers/:id/drops/:drop_id/comments/:comment_id
buckets/:id/drops/:drop_id/comments/:comment_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
comment_id	Int64	Required	The numerical id of the comment being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/1234/comments/34

POST (rivers or buckets)/:id/drops/:drop_id/links

Add a link to a drop.

Resource Path

rivers/:id/drops/:drop_id/links
buckets/:id/drops/:drop_id/links

Request parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.

Request body structure

The request body is a JSON representation of the Link.

Example Request

POST https://api.swiftapp.com/v1/rivers/9/drops/1234/links

POST DATA

{
   "url":"http://ushahidi.com/"
}

Response

{
   "id":1111,
   "url":"http://ushahidi.com/"
}

DELETE (rivers or buckets)/:id/drops/:drop_id/links/:link_id

Delete an existing link.

Resource Path

(rivers or buckets)/:id/drops/:drop_id/links/:link_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
link_id	Int64	Required	The numerical id of the link being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/1234/links/34

POST (rivers or buckets)/:id/drops/:drop_id/media

Add a media to a drop.

Resource Path

rivers/:id/drops/:drop_id/media
buckets/:id/drops/:drop_id/media

Request parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.

Request body structure

The request body is a JSON representation of the Media.

Example Request

POST https://api.swiftapp.com/v1/rivers/9/drops/1234/media

POST DATA

{
   "url":"http://ushahidi.com/image.jpg",
   "type":"image"
}

Response

{
   "id":1111,
   "url":"http://ushahidi.com/image.jpg",
   "type":"image"
}

DELETE (rivers or buckets)/:id/drops/:drop_id/media/:media_id

Delete an existing media.

Resource Path

rivers/:id/drops/:drop_id/media/:media_id
buckets/:id/drops/:drop_id/media/:media_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
media_id	Int64	Required	The numerical id of the media being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/1234/media/34

POST (rivers or buckets)/:id/drops/:drop_id/tags

Add a tag to a drop.

Resource Path

rivers/:id/drops/:drop_id/tags
buckets/:id/drops/:drop_id/tags

Request parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.

Request body structure

The request body is a JSON representation of the Tag.

Example Request

POST https://api.swiftapp.com/v1/rivers/9/drops/1234/tags

POST DATA

{
   "tag":"A New Tag",
   "tag_type":"thing"
}

Response

{
   "id":1111,
   "tag":"A New Tag",
   "tag_type":"thing"
}

DELETE (rivers or buckets)/:id/drops/:drop_id/tags/:tag_id

Delete an existing tag.

Resource Path

rivers/:id/drops/:drop_id/tags/:tag_id
buckets/:id/drops/:drop_id/tags/:tag_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
tag_id	Int64	Required	The numerical id of the tag being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/1234/tags/34

POST (rivers or buckets)/:id/drops/:drop_id/places

Add a place to a drop.

Resource Path

rivers/:id/drops/:drop_id/places
buckets/:id/drops/:drop_id/places

Request parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.

Request body structure

The request body is a JSON representation of the Place.

Example Request

POST https://api.swiftapp.com/v1/rivers/9/drops/1234/places

POST DATA

{
   "name":"Utopia",
   "type":"point",
   "coordinates":[
      [
         2.2241006,
         48.8155414
      ]
   ]
}

Response

{
   "id":1111
   "name":"Utopia",
   "type":"point",
   "coordinates":[
      [
         2.2241006,
         48.8155414
      ]
   ]
}

DELETE (rivers or buckets)/:id/drops/:drop_id/places/:place_id

Delete an existing place.

Resource Path

rivers/:id/drops/:drop_id/places/:place_id
buckets/:id/drops/:drop_id/places/:place_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
place_id	Int64	Required	The numerical id of the place being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/1234/places/34

POST (rivers or buckets)/:id/drops/:drop_id/forms

This endpoint is used to add predefined custom form fields to a drop.

Resource Path

rivers/:id/drops/:drop_id/forms
buckets/:id/drops/:drop_id/forms

Request Parameters

Field	Type	Description
id	Required	The identifier for the river or bucket the drop being modified is in.
drop_id	Required	The identifier for the river or drop being modified.

Request Body

The request body is a FormValue object that has the following fields:

Field	Type	Read/Write	Description
id	String	RW	The form identifier.
values	FieldValues	RW	List of FieldValues for the form.

FieldValues have the following fields:

Field	Type	Read/Write	Description
id	String	RW	The form field identifier.
value	String	RW	The value for the for field.

Example Request

Assuming the following form has been defined:

{
   "id":"1234",
   "name":"Hate Speech Categorisation",
   "fields":[
      {
         "id":"13",
         "title":"Language",
         "description":"Language the audience is being addressed in",
         "type":"mutiple",
         "required":false,
         "options":[
            "English",
            "Swahili",
            "Luo",
            "Kalenjin",
            "Luhya",
            "Kikuyu",
            "Sheng",
            "Other"
         ]
      },
      {
         "id":"14",
         "title":"Speaker",
         "description":"Description of the speaker",
         "type":"select",
         "required":false,
         "options":[
            "Politician",
            "Journalist",
            "Blogger",
            "Community Leader",
            "Anonymous Commenter",
            "Identifiable Commenter",
            "Public Figure"
         ]
      },
      {
         "id":"15",
         "title":"Target Audience",
         "description":"Audience most likely to react to this statement/article",
         "type":"text",
         "required":true
      }
   ]
}

The following request will add field values for the form to a drop:

POST https://api.swiftapp.com/v1/rivers/9999/forms

POST DATA

{
   "id":1234,
   "values":[
      {
         "id":13,
         "value":[
            "English",
            "Swahili"
         ]
      },
      {
         "id":14,
         "value":"Journalist"
      },
      {
         "id":15,
         "value":"Kenyan people"
      }
   ]
}

Response

{
   "id":1234,
   "values":[
      {
         "id":13,
         "value":[
            "English",
            "Swahili"
         ]
      },
      {
         "id":14,
         "value":"Journalist"
      },
      {
         "id":15,
         "value":"Kenyan people"
      }
   ]
}

PUT (rivers or buckets)/:id/drops/:drop_id/forms/:form_id

This endpoint is used to modify form field values existing in a drop.

Resource Path

rivers/:id/drops/:drop_id/forms/:form_id
buckets/:id/drops/:drop_id/forms/:form_id

Request Parameters

Field	Type	Description
id	Required	The identifier for the river or bucket the drop being modified is in.
drop_id	Required	The identifier for the river or drop being modified.
form_id	Required	The identifier for the form being modified.

Request Body

JSON representaiton of the field values being modified:

Example Request

The following request will add update the specified field values:

PUT https://api.swiftapp.com/v1/rivers/9999/forms/1234

PUT DATA

{
   "id":1234,
   "values":[
      {
         "id":13,
         "value":[
            "French"
         ]
      }
   ]
}

Response

{
   "id":1234,
   "values":[
      {
         "id":13,
         "value":[
            "French"
         ]
      },
      {
         "id":14,
         "value":"Journalist"
      },
      {
         "id":15,
         "value":"Kenyan people"
      }
   ]
}

DELETE (rivers or buckets)/:id/drops/:drop_id/forms/:form_id

Delete an existing form.

Resource Path

rivers/:id/drops/:drop_id/forms/:form_id
buckets/:id/drops/:drop_id/forms/:form_id

Request Parameters

Field	Type	Required	Description
id	String	Required	The identified for the river/bucket the drop is in.
drop_id	String	Required	The drop identifier.
form_id	Int64	Required	The identifier of the form to be removed.

Example Request

DELETE https://api.swiftapp.com/v1/rivers/9/drops/9999/forms/1234

PUT (rivers or buckets)/:id/drops/read/:drop_id

Resource Paths

rivers/:id/drops/read/:drop_id
buckets/:id/drops/read/:drop_id

Request Parameters

Field	Type	Description
id	Int64	The identifier of the river or bucket
drop_id	Int64	The identifier of the drop within the river or bucket

Example Requests

PUT https://api.swiftapp.com/v1/rivers/1/drops/read/8746

PUT https://api.swiftapp.com/v1/buckets/5/drops/read/73528