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 Calender API and access the administrator web interface.
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 Calendar 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 administrator web interface, you're ready to learn about...
how to authenticate the user
adding a "Hello World" event
Personal Calendar API methods in detail
Personal Calendar 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 calendar 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 Calendar API calls.
Below is an example of how the call is made:
|
Format:
[PersonalCalendarV1URL]?action=[action name]&
token=[user token]¶m=[value]...
Example:
[PersonalCalendarV1URL]?action=addevent&token=Hjlkzjlfkzef23423kjlkjr&
param=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" event
Adding a "Hello World" event to the calendar of an Orange customer is easy.
Firstly, retrieve a user token using the Authentication API. This user token will be used as the "token" parameter in the Personal Calendar 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" event):
|
[PersonalCalendarV1EndPoint]?action=addevent&title=Hello%20World&
location=&description=&startdate=21/06/2008&starttime=20:00&
enddate=21/06/2008&endtime=21:00&datepattern=dd/MM/yyyy&
timepattern=HH:mm&token=Hjlkzjlfkzef23423kjlkjr |
The above code will add the event to the user's Orange calendar. Easy.
Personal Calendar API methods in detail
Personal Calendar API provides four methods:
addevent
addeventoffline
geteventlist (coming soon)
checkavailability (coming soon)
addevent
Add an event to the calendar of an Orange France customer.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
|
Format:
[PersonalCalendarV1EndPoint]?action=addevent&title=[title]&
location=[location]&description=[description]&startdate=[start date]&
starttime=[start time]&enddate=[end date]&endtime=[end time]&
datepattern=dd/MM/yyyy&timepattern=HH:mm&token=[user token]
Example:
[PersonalCalendarV1EndPoint]?action=addevent&title=test&
location=some%20location&description=some%20description&
startdate=10/01/2000&starttime=10:00&enddate=10/01/2000&
endtime=11:00&datepattern=dd/MM/yyyy&timepattern=HH:mm&
token=Hjlkzjlfkzef23423kjlkjr |
input parameters
| Name |
Description |
Mandatory |
Type |
| title |
the title of the event |
Yes |
String |
| startdate |
start date of event |
Yes |
Date |
| enddate |
end date of event |
Yes |
Date |
| starttime |
start time of event |
Yes |
Time |
| endtime |
end time of event |
Yes |
Time |
| datepattern |
date format, value = dd/MM/yyyy |
Yes |
String |
| timepattern |
time format, value = HH:mm |
Yes |
String |
| description |
description of the event |
Yes |
String |
| location |
location of the event |
Yes |
String |
| token |
user token that is retrieved using the Authentication API |
Yes |
String |
sample response
If the event is correctly added, the response will contain the event ID and a result = 0. It will look like the following:
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="cauupdate" request="s01">
<event-data>
<eventid>4790</eventid>
<id>10012000</id>
</event-data>
<result>0</result>
</command>
</command-list>
<parameter-list />
</xpage> |
(back to API methods in detail)
addeventoffline
Add an event to the calendar of an Orange France customer even if he is disconnected (with an old user token), the validity period for this operation is longer than for the addevent operation.
To call the API, create the following URL format in your web application and invoke it through HTTP GET:
Format:
[PersonalCalendarV1EndPoint]?action=addeventoffline&title=[title]&
location=[location]&description=[description]&startdate=[start date]&
starttime=[start time]&enddate=[end date]&endtime=[end time]&
datepattern=dd/MM/yyyy&timepattern=HH:mm&token=[user token]
Example:
[PersonalCalendarV1EndPoint]?action=addeventoffline&title=test&
location=some%20location&description=some%20description&
startdate=10/01/2000&starttime=10:00&enddate=10/01/2000&
endtime=11:00&datepattern=dd/MM/yyyy&timepattern=HH:mm&
token=Hjlkzjlfkzef23423kjlkjr
|
The input parameters, the response and the error codes are same as the addevent operation.
(back to API methods in detail)
Personal Calendar API error codes
When an error occurs, the response contains an error code ('type' parameter), an internal subtype and the message:
|
<command request="" action="action">
<result>-yyy</result>
<error subtype="xxx" type="yyy">message</error>
</command> |
Here is a table which describes the most significant errors:
| Error Code |
Message |
| 1 |
'mandatory parameter' is missing. |
| 2 |
'parameter' is invalid. |
| 4 |
The command 'action' is unknown. |
| 5 |
'end-userid' is incorrect (database is corrupted). |
| 100 |
Service Calendar not provisioned for this end-user. |
(back to top)
