Skip to content

Create stream

Jump to bottom
rafael edited this page Feb 23, 2012 · 2 revisions

Description.

Photos are uploaded directly to S3 to be as fast as possible. The process involves the following steps:

  • An initial request to Piictu API to retreive credentials to upload photo to S3.
  • Upload the file to S3.
  • Pass the S3 photo url to piictu to create the stream.

The steps are described in detail in the following sections.

##Request to Create Stream

###URL: GET http://public-api.piictu.com/v2/streams/new

###HTTP method(s): GET

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

###Usage example:

Example using cURL:

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

###Response:

On success

  • HTTP response code is 200 (OK)
  • HTTP response body is a JSON string like this:
{
  "photo_id":"4dc216465a0d033da8000001",
  "s3_params":{
    "access_key":"AKIAI4ODBVR666JZ5DCA",
    "key":"photos/4dc216465a0d033da8000001/original",
    "policy":"eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDM6MjU6MTguMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIxNjQ2NWEwZDAzM2RhODAwMDAwMS9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgICAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9",
    "signature":"WCHgES1e6vjX32DvbBKJgoSmTuM=",
    "sas":"201",
    "bucket":"piictu-dev"
  },
  "s3_thumbnail":{
    "access_key":"TRIAI4ODBVR666JZ5BX",
    "key":"photos/4dc216465a0d033da8000001/90x90",
    "policy":"eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDM6MjU6MTguMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIxNjQ2NWEwZDAzM2RhODAwMDAwMS9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgICAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9",
    "signature":"WCHgES1e6vjX32DvbBKJgoSmTuM=",
    "sas":"201",
    "bucket":"piictu-dev"
  }
}

Note: Save the photo_id to send it back to Piictu API when create the stream

##Upload to S3 (the photo and thumbnail)

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-staging.s3.amazonaws.com \
 -F key="photos/4dc216465a0d033da8000001/original" \
 -F AWSAccessKeyId=AKIAI4ODBVR666JZ5DCA \
 -F acl=public-read \
 -F policy=eydleHBpcmF0aW9uJzogJzIwMTEtMDUtMDVUMDM6MjU6MTguMDAwWicsCiAgICAgICAgICAnY29uZGl0aW9ucyc6IFsKICAgICAgICAgICAgeydidWNrZXQnOiAncGlpY3R1LWRldid9LAogICAgICAgICAgICBbJ2VxJywgJyRrZXknLCAncGhvdG9zLzRkYzIxNjQ2NWEwZDAzM2RhODAwMDAwMS9vcmlnaW5hbCddLAogICAgICAgICAgICBbJ3N0YXJ0cy13aXRoJywgJyRDb250ZW50LVR5cGUnLCAnJ10sCiAgICAgICAgICAgIHsnYWNsJzogJ3B1YmxpYy1yZWFkJ30sCiAgICAgICAgICAgIHsnc3VjY2Vzc19hY3Rpb25fc3RhdHVzJzogJzIwMSd9LAogICAgICAgICAgICBbJ2NvbnRlbnQtbGVuZ3RoLXJhbmdlJywgMCwgNDE5NDMwNF0KICAgICAgICAgIF0KICAgICAgICB9 \
 -F signature=WCHgES1e6vjX32DvbBKJgoSmTuM= \
 -F success_action_status=201 \
 -F Content-Type="image/jpeg" \
 -F "file=@stl-park1.jpeg" \
 -X POST

Do the same for the photo and the thumbnail

###Response from S3:

  • HTTP response code is 201 (Created)
  • HTTP location is set to an url like http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal pointing to avatar just created in S3
  • HTTP response body is a XML like this:
<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
  <Location>http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal</Location>
  <Bucket>piictu-dev</Bucket>
  <Key>photos/4dc216465a0d033da8000001/original</Key>
  <ETag>"e4c2508e016da690982a594ad44e70e9"</ETag>
</PostResponse>

##Create the stream using the photo and the thumbnail uploaded to S3

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

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

###HTTP method(s): POST

###Parameters:

  • stream[locked] (optional:boolean): indicates if the stream will be locked (just the people mentioned can access it)
  • 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] (optional:string): the S3 url return by S3 (in the example: http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2F90x90). If the thumbnail is not provided, the Piictu will generate one for you in the background.
  • 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 (sending 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 invitation you can use this alternative syntax:

photo[invitations]="scott@example.com"
  • share[] (optional: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 \
 -F photo[_id]=4dc216465a0d033da8000001 \
 -F photo[url]=http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal \
 -F photo[thumbnail]=http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2F90x90 \
 -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 POST \
 -H "Authorization: OAuth 2540af0de121516b8477b0b7bd66dbd8ab6840b147340c6898c4eebd"

###Response:

On success

  • HTTP response code is 201 (created)
  • HTTP location is set to an url like http://api.piictu.com/v1/streams/4d6ef7e05243be1fc6000001 pointing to the address of the resource just created
  • HTTP response body is a JSON string like this:
{
  "stream":{
    "created_at":"2011-05-04T23:03:19-04:30",
    "locked":false,
    "seq":13045663993051284,
    "updated_at":"2011-05-04T23:03: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",
        "url":"http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal",
        "thumbnail":null,
        "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":"first-stream",
          "created_at":"2011-05-04T23:03:19-04:30",
          "seq":13045663993102892,
          "stream_id":"4dc21a7f5a0d033da8000002",
          "url":"http://piictu-dev.s3.amazonaws.com/photos%2F4dc216465a0d033da8000001%2Foriginal",
          "thumbnail":null,
          "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"]
  }
}

Clone this wiki locally