before getting started
Before getting started, please read the information below, and follow any instructions.
You'll then be ready to move onto the 'getting started' section.
two things to do before you get started
all about the API manager
two things to do before you get started
To start playing with this API, please make sure you have read and understood the
Personal APIs (alpha) section
 |
You need to be an Orange Partner Member in order to use the
Personal Photos API and access the API Manager.
If not already, become an Orange Partner member now
|
 |
Access the API Manager |
And then, within the API Manager, you'll be able to subscribe to the Personal Photos API.
|
all about the API Manager
The API Manager allows you to control and configure all aspects of your Personal APIs alpha subscriptions.
Specifically you'll be able to:
gain immediate approval to use the APIs
request subscription to any or all of the APIs
gain approval for your subscription
and then receive your access key, endpoint URLs, sample codes and advanced technical documentation
|
|
The steps below describe important aspects of the interface:
The first time you log on to the API Manager, we will ask you to fill in a form to provide us with information that includes:
your website URL
your website name
your website logo
This information will help us validate your subscription.
The website information you provide will be displayed to the users to enable them to set their privacy settings, and will determine if the users will allow you - the developer - to access their personal information via the Personal APIs.
You will then have access to a screen, allowing you to request a subscription to any of the APIs.
Remember, you MUST subscribe to the Authentication API first.
Once your subscription has been validated, you will receive an email and a ZIP file containing the following:
Your access key (SERVICE_ID and SERVICE PWD)
The API endpoint URL
Sample codes
Instructions on how to use it all.
access the API Manager
getting started
Now that you've read the 'before getting started' section, and become familiar with API Manager, you're ready to learn about...
how to authenticate the user
adding a "Hello World" photo album
Personal Photos API methods in detail
Personal Photos API error codes
Also, make sure your familiar with the Personal APIs privacy management process.
The process protects Orange users by preventing third parties from accessing their personal data without their permission. Find out more
how to authenticate the user
Firstly, users need to be authenticated before access to their photos is granted.
The authentication is done through the Authentication API which will return a user token.
You will then include the user token in all Personal Photos API calls.
Below is an example of how the call is made:
|
Format:
[PersonalPhotosV1URL]?action=[action name]&
token=[user token]¶m=[value]...
Example:
[PersonalPhotosV1URL]?action=CreateAlbum&
token=Hjlkzjlfkzef23423kjlkjr¶m=value...
|
If you want to see whether your code has worked, we can provide you with an Orange customer test account, so you can see the results as if you were an Orange customer. Once your subscription is validated, we'll show you how you can get one.
adding a "Hello World" photo album
Adding a "Hello World" photo album to the user's Orange photo account is easy.
Firstly, retrieve a user token using the Authentication API. This user token will be used as the "token" parameter in the Personal Photos API call.
For more information, see how to authenticate the user section.
You will then be able to call the following request (adding a "Hello World" album):
|
[PersonalPhotosV1EndPoint]?action=CreateAlbum&
title=Hello%20World&token=Hjlkzjlfkzef23423kjlkjr |
The above code will create a new album called "Hello World" to the user's Orange photo account. Easy.
Personal Photos API methods in detail
Personal Photos API provides the following methods:
GetAlbumList - get the albums of the given user
CreateAlbum - create an album
GetAlbum - retrieve one of the user's albums
GetMediaObjsList - get an album's list of photos
GetMediaObj - get information about a photo
AddMediaObj - add a photo
GetAlbumList - get the albums of the given user
This action retrieves the given user's albums list. It returns a summary of the albums.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalPhotosV1URL]?action=GetAlbumsList&
token=[user token]
Example:
[PersonalPhotosV1URL]?action=GetAlbumsList&
token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| token |
user token that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3201">
<albums count="3">
<album cypheredId="4f7mr0vqj3wk5">
<title><![CDATA[album 8/2/2006-01]]></title>
<guests count="2"/>
<mediaObjects count="4"/>
</album>
<album cypheredId="2g7x1pi3kuyva">
<title><![CDATA[album 21/3/2006-01]]></title>
<guests count="3"/>
<mediaObjects count="3"/>
</album>
<album cypheredId="1hvdkd3k0womr">
<title><![CDATA[title]]></title>
<guests count="1"/>
<mediaObjects count="12"/>
</album>
</albums>
</action> |
description of the album node:
| Name |
Description |
Type |
Example |
| album |
node used to describe an album |
|
|
| title |
title of the album |
string |
album 8/2/2006-01 |
| guests |
number of guests on this album (not used) |
integer |
2 |
| mediaObjects |
number of media objects of the album |
integer |
4 |
(back to Personal Photos API methods)
Create Album - create an album
This action creates an album. If the album already exists in the database, it will automatically be renamed as <title>< -n > (where n is an integer).
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalPhotosV1URL]?action=CreateAlbum&
TIT=[album title]&token=[user token]
Example:
[PersonalPhotosV1URL]?action=CreateAlbum&
TIT=album%2010/12/2006-01&
token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| TIT |
title of the album |
yes |
string |
| token |
user token that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="100">
<album cypheredId="ny1qpf7uv545">
<title><![CDATA[album 10/12/2006-01]]></title>
<creationDate>1166212233028</creationDate>
</album>
</action> |
description of the album node:
| Name |
Description |
Type |
Example |
| album |
node used to describe an album |
|
|
| title |
title of the album |
string |
album 10/12/2006-01 |
| creationDate |
creation date of the album (UTC date) |
integer long |
1166212233028 |
(back to Personal Photos API methods)
GetAlbum - retrieve one of the user's albums
This action allows the given user to retrieve one of its albums using its cyphered identifier.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalPhotosV1URL]?actionGetAlbum&
Album=[Cypheredld]&token=[user token]
Example:
[PersonalPhotosV1URL]?actionGetAlbum&
Album=ny1qpf7uv545&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| album |
cyphered id of the album to be recovered |
yes |
string |
| token |
user token that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="105">
<album cypheredId="ny1qpf7uv545">
<title><![CDATA[album 10/12/2006-01]]></title>
<creationDate>1166212233028</creationDate>
</album>
</action> |
description of the album node:
| Name |
Description |
Type |
Example |
| album |
node used to describe an album |
|
|
| title |
title of the album |
string |
album 10/12/2006-01 |
| creationDate |
creation date of the album (UTC date) |
integer long |
1166212233028 |
(back to Personal Photos API methods)
GetMediaObjsList - get an album's list of photos
This action retrieves the photos of the album which cyphered identifier is passed in parameter.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalPhotosV1URL]?actionGetMediaObjsList&
Album=[CypheredId]&token=[user token]
Example:
[PersonalPhotosV1URL]?actionGetMediaObjsList&
Album=ny1qpf7uv545&token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| album |
cyphered id of the album to be recovered |
yes |
string |
| token |
user token that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3204">
<mediaObjects>
<mediaObject id="5922" cypheredId="c0f8aae730f9552e">
<title><![CDATA[2005-Porsche-911]]></title>
<creationDate>1145433318470</creationDate>
<filename>porsche_911.jpeg</filename>
<filesize>212117</filesize>
<mimeType>image/jpeg</mimeType>
<width>1920</width>
<height>1440</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?
cid=c0f8aae730f9552e&app=ephoto.orange.fr
</baseUrl>
</mediaObject>
<mediaObject id="5923" cypheredId="a8ef26337d8b6c6d">
<title><![CDATA[2005-TechArt]]></title>
<creationDate>1145433328663</creationDate>
<filename>techart.jpeg</filename>
<filesize>162393</filesize>
<mimeType>image/jpeg</mimeType>
<width>1024</width>
<height>768</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?
cid=a8ef26337d8b6c6d&app=ephoto.orange.fr
</baseUrl>
</mediaObject>
</mediaObjects>
</action> |
description of the mediaObject node:
| Name |
Description |
Type |
Example |
| title |
title of the mediaObject |
string |
2005-Porsche-911 |
| creationDate |
creation date of the media object (UTC date) |
integer long |
1145433328663 |
| filename |
name of the file in the filer |
string |
porsche_911.jpg |
| filesize |
size of the file in the filer, in bytes |
integer long |
212117 |
| mimeType |
mime type of object |
string |
image/jpeg |
| width |
width of the image in pixels |
integer |
1920 |
| height |
height of the image in pixels |
integer |
1440 |
| baseURL |
URL to retrieve the photo |
string |
|
(back to Personal Photos API methods)
GetMediaObj - get information about a photo
This method retrieves information about a photo by passing the photo cyphered identifier in the URL. The photo identifier can be retrieved using the GetMediaObjsList method.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalPhotosV1URL]?action=GetMediaObj&MOB=[MediaObjCypheredId]&
token=[user token]
Example:
[PersonalPhotosV1URL]?action=GetMediaObj&MOB=c0f8aae730f9552e&
token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| MOB |
media object's cyphered identifier |
yes |
integer |
| token |
user token that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3205">
<mediaObject id="5922" cypheredId="c0f8aae730f9552e">
<title><![CDATA[2005-Porsche-911]]></title>
<creationDate>1145433318470</creationDate>
<filename>porsche_911.jpeg</filename>
<filesize>212117</filesize>
<mimeType>image/jpeg</mimeType>
<width>1920</width>
<height>1440</height>
<baseUrl>
http://ephoto.orange.fr/sitdriver?cid=c0f8aae730f9552e&app=papi
</baseUrl>
</mediaObject>
</action> |
description of the mediaObject node:
| Name |
Description |
Type |
Example |
| title |
title of the mediaObject |
string |
2005-Porsche-911 |
| creationDate |
creation date of the media object (UTC date) |
integer long |
1145433328663 |
| filename |
name of the file in the filer |
string |
porsche_911.jpg |
| filesize |
size of the file in the filer, in bytes |
integer long |
212117 |
| mimeType |
mime type of object |
string |
image/jpeg |
| width |
width of the image in pixels |
integer |
1920 |
| height |
height of the image in pixels |
integer |
1440 |
| baseURL |
URL to retrieve the photo |
string |
|
photo retrieval
The GetMediaObj and GetMediaObjsList methods return the baseUrl of the photo, this is where the photo can be downloaded.
Furthermore, you can ask modifications on the photo, such as resizing. In that case, additional parameters must be added to the baseURL:
width: maximum width in pixels
height: maximum height in pixels
To get a better response time, we strongly encourage you to use 100 x 100 and 500 x 500 pixels thumbnails which have been precomputed.
(back to Personal Photos API methods)
AddMediaObj - add a photo
This action adds a photo to the album which cyphered identifier is passed in parameter. This request contains the image file to be transferred to the Photo server.
The following formats are accepted:
image: JPEG, GIF, BMP, PNG
To call the API, create the following URL format in your web application and invoke it through HTTP POST:
|
Example:
Content-Type: multipart/form-data;
boundary=---------------------------41184676334
Content-Length: 29277
-----------------------------41184676334
Content-Disposition: form-data; name="action"
AddMediaObj
-----------------------------41184676334
Content-Disposition: form-data; name="Album"
582ba38athhqv
-----------------------------41184676334
Content-Disposition: form-data; name="F_title"
title
-----------------------------41184676334
Content-Disposition: form-data; name="token"
Hjlkzjlfkzef23423kjlkjr
-----------------------------41184676334
Content-Disposition: form-data; name="F"; filename="picture.jpg"
Content-Type: image/jpeg
... |
input parameters
| Name |
Description |
Mandatory |
Type |
| Album |
cyphered id of the album
if no album is specified, the inbox album will be used |
no |
string |
| F |
file to be transferred |
yes |
string |
| F_title |
title of the file to be transferred |
yes |
string |
| token |
identifier of the user that is retrieved using the Authentication API |
yes |
string |
sample response
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="3201">
<albums count="3">
<album cypheredId="4f7mr0vqj3wk5">
<title><![CDATA[album 8/2/2006-01]]></title>
<guests count="2"/>
<mediaObjects count="4"/>
</album>
<album cypheredId="2g7x1pi3kuyva">
<title><![CDATA[album 21/3/2006-01]]></title>
<guests count="3"/>
<mediaObjects count="3"/>
</album>
<album cypheredId="1hvdkd3k0womr">
<title><![CDATA[title]]></title>
<guests count="1"/>
<mediaObjects count="12"/>
</album>
</albums>
</action> |
(back to Personal Photos API methods)
Personal Photos API error codes
When an error occurs, the response contains the following parameters:
|
<?xml version="1.0" encoding="UTF-8"?>
<action version="2.0" code="200">
<error-code>1106</error-code>
<error-msg>
Owner unknown [GUID = mail jsmith@orange.fr]
</error-msg>
</action> |
Here is a table which describes the most significant errors:
| Code |
Status |
Description |
| 200 |
OK |
The HTTP request succeeded.
For a GET request: the entity corresponding to the requested resource is sent in the response.
For a POST request: an entity containing the result of the action is sent in the response. |
| 400 |
Bad Request |
The HTTP request could not be understood by the server due to malformed syntax. |
| 404 |
Not Found |
The server has not found anything matching the requested address (URL). |
| 500 |
Internal Server Error |
The server encountered an unexpected condition which prevented it from fulfilling the request. |
(back to top)
