Open topic with navigation

Conventions

The Conventions section explains the documentation conventions, the code conventions that are used in the examples and methods, as well as general Photobucket conventions.

Documentation Conventions

In the documentation, the following conventions are observed:

• All Sample Requests in each method use bold, red text to call out the action that the request is performing.
• All Sample Responses in each method are XML.
• POST is represented by the request URL, then the www-urlencoded-data of the post in any Sample Requests that use POST.  
  

Example

POST http://api.photobucket.com/login/access

oauth_consumer_key=00000000&oauth_nonce=GOUFIE&oauth_signature_method=HMAC-S HA1&oauth_timestamp=1207064755&oauth_token=req_1a8d7b9bb26f0f25c62691481558f 81448bac652&oauth_signature=2ggT37NAys3P6xZGoSDhp40twF0=

• PUT is represented like GET or DELETE, with all options in the query string, assuming an empty payload in any Sample Request that uses PUT.

Example

PUT http://api.photobucket.com/ping?format=xml&oauth_consumer_key=00000000&oauth _nonce=997c5f008a7fb22e76df4cef4633845e&oauth_signature=jXH3fqtAmGGcbajk269e 5H%2FhxXg%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1203443499&oau th_token=28.1&oauth_version=1.0

Code Conventions

Photobucket Conventions

Photobucket provides specific URL structures that can be used by applications, supports specific media types, and requires that requests be encoded in a specific manner. The Photobucket web site also has certain structural conventions that pertain to object encoding.

Supported Media Types 

Photobucket supports image and video media types. The accepted media types are:

• Image – jpg, png, gif, base 64 encoded image, or bmp (Photobucket re-encodes bmp to jpg).
• Video – 3g2, 3gp, 3gp2, 3gpp, 3p, asf, avi, divx, dv, dvx, flv, gif, moov, mov, mp4, mpeg4, mpg4, mpe, mpeg, mpg, qt, swf, wmv, xvid, or rm. (Photobucket re-encodes all videos to Flash video).

URL Structures 

Photobucket provides "special" URL prefaces that you should use for various types of display and linking. The following table pertains to images and videos, lists the sub-domain preface, and provides a description of how it should be used.

Request Encoding

The following conventions must be observed when sending requests:

• All GET requests must be encoded with URL encoded parameters.
• All POST, PUT, and DELETE requests must be encoded with URL encoded parameters or with text/www-urlencoded-data.
• The only exception is a file upload POST request which must be encoded with multipart/form-data.

Example Multipart Encoded POST Upload Request

POST http://api202.photobucket.com/album/pbapi/upload

Content-Type: multipart/form-data; boundary=xx4831d34894cec

--xx4831d34894cec

content-disposition: form-data; name="oauth_version"

 

1.0

--xx4831d34894cec

content-disposition: form-data; name="oauth_nonce"

 

6d6961436882002b1a74f0ed2c049d30

--xx4831d34894cec

content-disposition: form-data; name="oauth_timestamp"

 

1211224904

--xx4831d34894cec

content-disposition: form-data; name="oauth_consumer_key"

 

00000000

--xx4831d34894cec

content-disposition: form-data; name="type"

 

image

--xx4831d34894cec

content-disposition: form-data; name="format"

 

xml

--xx4831d34894cec

content-disposition: form-data; name="oauth_token"

 

31.6_1211224899

--xx4831d34894cec

content-disposition: form-data; name="oauth_signature_method"

 

HMAC-SHA1

--xx4831d34894cec

content-disposition: form-data; name="oauth_signature"

 

yYYko9YCDLzE2QcEi0fkiaPkhoU=

--xx4831d34894cec

content-disposition: form-data; name="uploadfile"; filename="blueraven.gif"

content-type: mimetype

content-transfer-encoding: binary

 

GIF89ad_....<rest of binary data>

--xx4831d34894cec

Object Identifiers

The Photobucket web site structure is:

User name > User album > Sub-albums > Sub-sub-albums, etc.

The user name is ALSO the main user album name.

For example, imagine a Photobucket user, pbapi. This user has three sub-albums, sub1, sub2, and sub3, and one sub-album, sub4 in album sub1. The user has media in these albums, image1, image2, and video1. SO:

User Name= pbapi

User Album = pbapi

Albums = sub1, sub2, sub3, and sub1/sub4

Media = image1 in the user album, image2 in album sub1, and video1 in album sub1/sub4

Additionally, group albums have their own "group hash value" or Group ID in their URLs. The Group ID is a short, all-caps string on the URL for a group. For example, the URL for the featured group album "Woof" is:

http://gs275.photobucket.com/groups/jj285/20IF1LMOT/?featuredgroupalbum=Woof

where 20IF1LMOT is the Group ID.

Get Album Request Examples

To GET the user album for user "pbapi", the request is:

http://api.photobucket.com/album/pbapi

To GET album "sub1" for user "pbapi", the request is:

http://api.photobucket.com/album/pbapi%2Fsub1

To GET album "sub4" for user "pbapi", the request is:

http://api.photobucket.com/album/pbapi%2Fsub1%2Fsub4

To GET the user album for the group "Woof" (hash value 20IF1LMOT), the request is: 

http://api.photobucket.com/group/20IF1LMOT 

Get Media Request Examples

To GET media from the user album (URL= http://api.photobucket.com/albums/gg17/pbapi/image1.gif), the request is:

http://api.photobucket.com/media/http%3A%2F%2Fphotobucket.com%2Falbums%2Fgg17%2Fpbapi%2Fimage1.gif 

Note: The "gg17" that is part of the URL is assigned by Photobucket. You can get the Photobucket-assigned value with any request that returns media or user information, for example, the Get User URL request or the Search Media request.

To GET media from the album "sub1" (URL= http://api.photobucket.com/albums/gg17/pbapi/sub1/image2.gif), the request is:

http://api.photobucket.com/media/http%3A%2F%2Fphotobucket.com%2Falbums%2Fgg17%2Fpbapi%2Fsub1%2Fimage2.gif

To GET media from the album "sub1/sub4" (URL= http://api.photobucket.com/albums/gg17/pbapi/sub1/sub4/video1.flv), the request is: 

http://api.photobucket.com/media/http%3A%2F%2Fphotobucket.com%2Falbums%2Fgg17%2Fpbapi%2Fsub1%2Fsub4%2Fvideo1.flv

To GET media from the group album "Woof" (hash value 20IF1LMOT), the request is:

http://api.photobucket.com/media/http%3A%2F%2Fphotobucket.com%2Fgroup%2Fjj285%2F20IF1LMOT%2Fimage1.gif

More examples are provided in the FAQ. See the topic What is the [identifier] in the Methods, and why does it look the way it does.

Alternative Identifier Specifications

Due to incompatibilities with some libraries, encoding slashes (/ to %2F) are not supported in the URL. In situations where slashes must be encoded, it is difficult to sign and make requests to albums and media objects. An alternative identifier specification has been devised as a work-around.

Put '!' in the URI in place of the identifier. The code assumes you are specifying "!" in the parameters (querystring or post).

If you put "!" in the first position (noted as ‘identifier’ in the documentation), the parameter is "id". E.g., /user/!/url?id=pbapi or /album/!?id=pbapi%2Fsecond

If you put "!" in the second position (noted as ‘actionIdentifier’ in the documentation), the parameter is "aid". E.g., /user/!/tag/!?id=pbapi&aid=tagname or /group/!/contributor/!?id=FFCGKTE2&aid=pbapi

Current User Identifier

When a user is logged in, some actions automatically support working on the current logged in user. To do this, specify "-" as the identifier.

Users: All actions (except register and suggest).

Albums: All actions (specifies user's root album).

Open topic with navigation