Skip to content

Reply stream

Jump to bottom
rafael edited this page Feb 25, 2012 · 3 revisions

Photos are uploaded directly to S3 to be as fast as possible. The process involves making an initial request to Piictu API retrieving a few parameters, passing them along with the file itself to S3, and pass the S3 photo url to Piictu API.

##Request to Reply to Stream

###URL: http://public-api.piictu.com/v2/streams/<stream id>/edit

###HTTP method(s): GET ###Requires authentication (Authentication and Authorization): Yes

Note: Save the id and photo_id to send them back to Piictu API when create the stream

###Usage example:

Example using cURL:

curl -i http://public-api.piictu.com/v2/streams/4dc21a7f5a0d033da8000002/edit \
-H "Authorization: OAuth 2540af0de12cb2367691516b8477b0b7bd66dbd8ab6840b147340c6898c4eebd"

###Response:

On success

  • HTTP response code is 200 (OK)
  • HTTP response body is a JSON string like this:
{
  "id":"4dc21a7f5a0d033da8000002",
  "photo_id":"4dc220385a0d033da8000004",
  "s3_params":{
    "access_key":"AKIAI4ODBVR666JZ5DCA",
    "key":"photos/4dc220385a0d033da8000004/original",
    "policy":"eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDQ6MDc6NDQuMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIyMDM4NWEwZDAzM2RhODAwMDAwNC9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgICAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9",
    "signature":"JG8f0ix/jUsrHnGDZ+vJGkHzQjk=",
    "sas":"201",
    "bucket":"piictu-dev"
  }
  "s3_thumbnail":{
    "access_key":"AKIAI4ODBVR666JZ5DCA",
    "key":"photos/4dc220385a0d033da8000004/90x90",
    "policy":"eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDQ6MDc6NDQuMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIyMDM4NWEwZDAzM2RhODAwMDAwNC9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgICAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9",
    "signature":"JG8f0ix/jUsrHnGDZ+vJGkHzQjk=",
    "sas":"201",
    "bucket":"piictu-dev"
  }
}

##Upload to S3

Use the response (s3_params and s3_thumbnail) from the previous step to construct the file upload request.

Each item in previous response becomes a separate parameter you’ll need to post to url. Send the file to be uploaded as the parameter named file.

Note: According to Amazon’s documentation, any parameter after file is ignored. Make sure file is last or the upload will be rejected.

###Usage example:

Example using cURL with placeholder for parameters:

curl -i http://<bucket>.s3.amazonaws.com \
 -F key=<key> \
 -F AWSAccessKeyId=<access_key> \
 -F acl=public-read \
 -F policy=<policy> \
 -F signature=<signature> \
 -F success_action_status=<sas> \
 -F Content-Type="image/jpeg" \
 -F "file=@stl-park1.jpeg" \
 -X POST

Example using cURL with parameters retrieved in previous step:

curl -i http://piictu.s3.amazonaws.com \
 -F key="photos/xxxxxx/original" \
 -F AWSAccessKeyId=AKIAI4ODBVR666JZ5DCA \
 -F acl=public-read \
 -F policy=eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDQ6MDc6NDQuMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIyMDM4NWEwZDAzM2RhODAwMDAwNC9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgIAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9 \
 -F signature=JG8f0ix/jUsrHnGD+vJGkHzQjk= \
 -F success_action_status=201 \
 -F Content-Type="image/jpeg" \
 -F "file=@stl-park1.jpeg" \
 -X POST

##Reply to the stream using the image and thumbnail uploaded to S3

Use the Location tag (or HTTP location header) in S3 response to reply the stream in Piictu

###URL: http://public-api.piictu.com/v2/streams/<id>

Here you use the id field retrieved in the first step (in the example: 4dc21a7f5a0d033da8000002)

###HTTP method(s): PUT

###Requires authentication (Authentication and Authorization): Yes

###Parameters:

  • photo[_id] (required:string): yes the param is underscore id (_id), this is the photo_id field returned by Piictu in the first step (in the example: 4dc216465a0d033da8000001)
  • photo[url] (required:string): the S3 url return by S3 (in the example: http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal)
  • photo[thumbnail] (required:string): the S3 url return by S3 (in the example: http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2F90x90)
  • photo[caption] (optional:string): caption for this photo
  • photo[mentions][] (optional:string user_id): mention users in this photo, this parameter can be present several times:
photo[mentions][]="4ceede9b5e6f991aef000006" photo[mentions][]="4ceede9b5e6f991aef000007"
  • photo[invitations][] (optional:string): invites people in this photo (send emails for now), this parameter can be present several times:
photo[invitations][]="scott@example.com" photo[invitations][]="foo@example.com"

If you have just one mention you can use this alternative syntax:

photo[invitations]="scott@example.com"
  • share[] (optionas:string) services to share the photo, this parameter can be present several times:
share[]="twitter" share[]="facebook"

###Usage example:

Example using cURL:

curl -i http://public-api.piictu.com/v2/streams/4d70df9f5a0d0312b6000001 \
 -F photo[_id]=4dc220385a0d033da8000004 \
 -F photo[url]=http://piictu-dev.s3.amazonaws.com/photos%2F4dc220385a0d033da8000004%2Foriginal \
 -F photo[thumbnail]=http://piictu-dev.s3.amazonaws.com/photos%2F4dc220385a0d033da8000004%2F90x90 \
 -F photo[caption]=second-photo \
 -F photo[invitations][]=scott@example.com \
 -F photo[invitations][]=tiger@example.com \
 -F photo[mentions][]="4ceede9b5e6f991aef000006" \
 -F photo[mentions][]="4ceede9b5e6f991aef000007" \
 -F share[]="facebook" \
 -F share[]="twitter" \
 -X PUT \
 -H "Authorization: OAuth 2540af0de121516b8477b0b7bd66dbd8ab6840b147340c6898c4eebd"

###Response:

On success

  • HTTP response code is 200 (ok)
  • HTTP response body is a JSON string like this:
{
  "stream":{
    "created_at":"2011-05-04T23:03:19-04:30",
    "locked":false,
    "seq":13045684399219890,
    "updated_at":"2011-05-04T23:37:19-04:30",
    "id":"4dc21a7f5a0d033da8000002",
    "original_photo":{
      "photo":{
        "caption":"first-stream",
        "created_at":"2011-05-04T23:03:19-04:30",
        "seq":13045663993102892,
        "stream_id":"4dc21a7f5a0d033da8000002",
        "thumbnail":"https://piictu-dev.s3.amazonaws.com/photos/4dc216465a0d033da8000001/90x90",
        "url":"http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal",
        "from":{
          "id":"4d6ebc4f5a0d032648000001",
          "username":"edgar",
          "fullname": null,
          "avatar_url":null
        },
        "id":"4dc216465a0d033da8000001",
        "mentions":[]
      }
    },
    "from":{
      "id":"4d6ebc4f5a0d032648000001",
      "username":"edgar",
      "fullname": null,
      "avatar_url":null
    },
    "photos":[
      {
        "photo":{
          "caption":"second-photo",
          "created_at":"2011-05-04T23:37:19-04:30",
          "seq":13045684399193390,
          "stream_id":"4dc21a7f5a0d033da8000002",
          "url":"http://piictu-dev.s3.amazonaws.com/photos%2F4dc220385a0d033da8000004%2Foriginal",
          "thumbnail":null,
          "from":{
            "id":"4d6ebc4f5a0d032648000001",
            "username":"edgar",
            "fullname": null,
            "avatar_url":null
          },
          "id":"4dc220385a0d033da8000004",
          "mentions":[]
        }
      },
      {
        "photo":{
          "caption":"first-stream",
          "created_at":"2011-05-04T23:03:19-04:30",
          "seq":13045663993102892,
          "stream_id":"4dc21a7f5a0d033da8000002",
          "thumbnail":"https://piictu-dev.s3.amazonaws.com/photos/4dc216465a0d033da8000001/90x90",
          "url":"http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal",
          "from":{
            "id":"4d6ebc4f5a0d032648000001",
            "username":"edgar",
            "fullname": null,
            "avatar_url":null
          },
          "id":"4dc216465a0d033da8000001",
          "mentions":[]
        }
      }
    ]
  }
}

On error

  • HTTP response code of 422 (Unprocesable entity)
  • HTTP response body is a JSON string like this:
{
  "error":{
    "photos":["Url can't be blank"]
  }
}

When stream identified by id don't exist

  • HTTP response code is 404 (document not found)
  • HTTP response body is a JSON string like this:
{
    "error" : "document not found"
}

If the stream is locked and user neither is mentioned in the stream or is the stream's creator

  • HTTP response code of 403 (Forbidden)
  • HTTP response body is a JSON string like this:
{
  "error" : "user not authorized"
}

Clone this wiki locally