English
Français
Tiếng ViệtSubmitted by Anonymous on
This documentation page aims at covering all the technical aspects of obm-sync.
It will describe how you, as a developer, can connect to an obm-sync instance in order to manage the calendars and address books of OBM users.
# Variables, Convention
Throughout this document, the following variables may be used:
| Name | Description | Value |
| ---- |
| OBM | The hostname or IP address of your OBM Apache frontend. | my.obm.local |
| ROOT | Root URL of your obm-sync server | /obm-sync/services/ |
| RC | HTTP Response Code | 200, 400, etc. |
In this document, a number of `curl` samples are given, allowing you to quickly test the invocation of any given method. If, by any chance, the `xmllint` utility is installed on your development machine (or if you want to install it, it is part of the _libxml2-utils_ package on major Linux distributions) we recommend piping the output of `curl` through the following command so that the resulting XML is formatted:
xmllint --pretty 1 -
# Protocol
OBM-Sync is an API that exposes a number of endpoints over HTTP(S).
To connect to the API, you must send HTTP(S) requests to the server, passing a number of parameters. The server will then process the request and send back a response.
A server response is composed of:
* An HTTP _response code_, as per the table below.
* A response _body_, if and only if the request was processed (this doesn't mean that the request has _succeeded_, just that it has been handled by the server). The response body is a _XML_ document which is context-dependent. See the documentation of the various endpoints below for an in-depth description of all returned XML documents.
### Requests
OBM-Sync accepts both _GET_ and _POST_ requests but we recommend the use of _POST_.
The target endpoint is selected by OBM-Sync depending on the URL. All URLs must have the following format:
### Available endpoints
The table below lists the available OBM-Sync endpoints. The available methods for each endpoint are listed in their dedicated section.
| ID | Name | Description |
| ----- |
| login | Session management endpoint | Allows clients to log in and out of the OBM-Sync server. |
| calendar | Calendar management endpoint | Allows clients to manage the calendars of OBM users. |
| book | Address book management endpoint | Allows clients to manage the address books of OBM users. |
#### FreeBusy
OBM-Sync supports free/busy requests using a special endpoint. The endpoint is reachable at _https://OBM/obm-sync/freebusy_.
See below for a complete description of this endpoint.
### Possible HTTP response codes
| Code | Name | Description |
| ---- |
| 200 | OK | Sent whenever the request was accepted and processed, event if the request eventually ends up in error. |
| 4xx | _Variable_ | Sent when the request was not accepted by the server. There's a number of possible causes but is often the result of a malformed URL. |
| 5xx | _Variable_ | Sent when there was an internal error during the processing of the request. |
### Errors
When a request ends up in error, the server will send an __error__ XML Document. The _error_ document has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| message | String | The error message raised by the server. | 0 or 1 |
| type | String | The type of the error, if applicable. | 0 or 1 |
Both the __message__ and the __type__ tags are optional, but at least one will be present in an _error_ document.
Following is a sample _error_ document, sent when a client tries to access a protected resource and his _session id_ is invalid or expired:
# Session management endpoint
All _business_ endpoints are protected, which means that a client must be logged-in to OBM-Sync before it can send requests to these endpoints.
To log in and out, a client uses the _session management endpoint_, which exposes the following methods.
### doLogin
This method allows a client to authenticate against the OBM-Sync server. The actual authentication method depends on the configuration and is not in the scope of this documentation.
The _doLogin_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| origin | Yes | The origin of the request. This can be any _String_. | N/A |
| login | Yes | The user _login_ to authenticate with. | N/A |
| password | Yes | The password associated with the above _login_. | N/A |
#### Returned XML document
Upon success, the _doLogin_ method returns a __token__ XML document. The _token_ document has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| sid | String | The session identifier. This is very important and must be sent back with every subsequent request to the other endpoints. | 1 |
| version | None | The version of the OBM-Sync server through the _major_, _minor_ and _release_ attributes. | 1 |
| email | String | The primary email address of the logged-in user. | 1 |
| domain | String | The domain name of the logged-in user. The _uuid_ attribute holds the universally unique identifier of the domain. | 1 |
| settings | List of _setting_ tags | The list of user settings. | 0 or 1 |
| setting | String | The value of a user setting. The _name_ attribute holds the name of the setting. | 1+ |
| server-capabilities | List of _server-capability_ tags. | The list of server capabilities | 0 or 1 |
| server-capability | String | Used by OBM-Sync to advertise support for a specific feature. The _name_ attribute holds the name of the supported feature. | 0+ |
Following is a sample _token_ document after a successful authentication:
##### `curl` sample
curl -sk -XPOST -d"origin=mySuperSyncClient" -d"login=usera" -d"password=****" https://OBM/ROOT/login/doLogin
### doLogout
This method allows a client to log out of an OBM-Sync server. The _doLogout_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
#### Returned XML document
This method doesn't return any XML document. A HTTP response code of 200 indicates that the call succeeded and the session was invalidated.
#### `curl` sample
curl -sk -XPOST -d"sid=6527b92a-2948-4c10-bdcf-fa8acb2d9693" https://OBM/ROOT/login/doLogout
# Address books management endpoint
The _address books management endpoint_ allows a client to create/modify/delete contacts in a user's address books. It also allows a client to receive changes that occurs server-side on address books and contacts.
### Common XML entities
#### Address book
An _address book_ is represented as a __folder__ XML document. The _folder_ XML document has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| folder | Address Book | The root tag. The _uid_ attribute holds the server unique identifier for this address book. | 1 |
| name | String | The name of this address book, as defined in OBM. | 1 |
| ownerDisplayName | String | The display name (common name) of the address book's owner. This tag will only be present if this address book is shared (i.e.: it doesn't belong to the logged-in user). | 0 or 1 |
| ownerLoginAtDomain | String | The _login@domain_ of this address book's owner. | 1 |
Following is a sample of a _folder_ XML document representing the _contacts_ address book of _userb_:
#### Contact
A contact is represented as a __contact__ XML document. The _contact_ XML document has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| contact | Contact | The root tag. The _collected_ attribute indicates whether this contact was automatically collected or created by the user. The _uid_ attribute holds the server unique identifier for this contact. | 1 |
| commonname | String | The common name (display name) of the contact | 0 or 1 |
| first | String | The first name of the contact | 0 or 1 |
| last | String | The last name of the contact | 1 |
| middlename | String | The middlename, if any, of this contact. | 0 or 1 |
| suffix | String | The suffix, if any, of this contact | 0 or 1 |
| service | String | The service this contact works in at his/her company. | 0 or 1 |
| title | String | The job title of this contact. | 0 or 1 |
| company | String | The company this contact works in. | 0 or 1 |
| aka | String | "Also Known As", the nickname of this contact. | 0 or 1 |
| comment | String | Any comment entered when this contact was first created. | 0 or 1 |
| manager | String | The name of this contact's manager, when applicable. | 0 or 1 |
| assistant | String | The name of this contact's assistant, when applicable. | 0 or 1 |
| addressbookid | Integer | The unique identifier of the address book containing this contact. | 1 |
| birthday | Integer | The timestamp of the contact's birthday. | 0 or 1 |
| anniversary | Integer | The timestamp of the contact's saint's day. | 0 or 1 |
| caluri | String | The URL to an iCal feed of the contact's calendar. | 0 or 1 |
| phones | List of _phone_ tags. | The list of all known phone numbers of this contact. | 0 or 1 |
| phone | None | The _label_ attribute is the identifier of the phone number and the _number_ attribute holds the number. | 1+ |
| addresses | List of _address_ tags | The list of all known addresses of this contact. | 0 or 1 |
| address | String | Holds a street address of this contact. The _label_ attribute is the identifier of this address and the other attributes holds the details of the address. | 1+ |
| websites| List of _site_ tags | The list of all known websites for this contact. | 0 or 1 |
| site | None | The _label_ attribute is the identifier of this website and the _url_ attribute id the website's URL. | 1+ |
| emails | List of _mail_ tags | The list of all known _email_ addresses of this contact. | 0 or 1 |
| mail | None | The _label_ attribute is the identifier of this email address and the _value_ attribute holds the actual address. | 1+ |
| instantmessaging | List of _im_ tags | the list of all known instant messaging addresses of this contact. | 0 or 1 |
| im | None | The _label_ attribute is the identifier of this instant messaging address, the _address_ attribute holds the actual address and the _protocol_ attribute is the protocol used. | 1+ |
In the above tags, the _label_ attribute must follow this convention:
[
where:
* _Type_ is the type of email address, instant messaging address, phone number, etc. Typical values for the _Type_ variable are: WORK, VOICE, CALURI, INTERNET, ...
* _n_ is simply a counter and must uniquely identify a element of any given _type_. For instance, the first email address would have _n=1_, the second one _n=2_, and so on because they're all email addresses so they have the same _Type_ attribute (_INTERNET_ in this case).
Following is a sample of a _contact_ XML document:
### getAddressBookSync
This method allows a client to receive changes to address books and contacts (it allows to be _in-sync_ with the OBM backend) of the logged-in user. It supports incremental synchronization.
The _getAddressBookSync_ method returns information for all address books that the logged-in user is subscribed to, including the shared ones. This method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| lastSync | No | The timestamp of the last successful synchronization done by the client. If given, only changes that occured _after_ this date will be sent. | 0 |
#### Returned XML document
Upon success, this method returns a __addressbook-changes__ XML document. The _addressbook-changes_ document has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| addressbook-changes | Address book changes | The _lastSync_ attribute is the synchronization timestamp. This is typically stored by the client and sent back later on. | 1 |
| addressbooks | List of changes to address books | The list of _removed_ and/or _updated_ addressbooks, represented by one or more _folder_ tags. See above for a description of this tag. | 0 or 1 |
| contacts | List of changes to contacts | The list of _removed_ and/or _updated_ contacts, represented by one or more _contact_ tags. See above for a description of this tag. | 0 or 1 |
| removed | List of removed elements | The list of removed elements. This is applicable to contacts and address books. | 1 |
| updated | List of updated elements | The list of updated (including newly created) elements. This is applicable to contacts and address books. | 1 |
| folder | Address book | A removed or updated address book. | 1+ |
| contact | Contact | A removed or updated contact. | 1+ |
Following is a sample _addressbook-changes_ document:
#### `curl` sample
curl -sk -XPOST -d"lastSync=1370442470034" -d"sid=a736ad7f-b458-4863-b6b6-2ac2cc864bc1" https://OBM/ROOT/book/getAddressBookSync
### createContact
This method allows a client to create a new contact in an address book. The _createContact_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| bookId | Yes | The unique identifier of the target address book. | N/A |
| contact | Yes | The XML document of the contact to create. See above for details. | N/A |
#### Returned XML document
Upon success, this method returns a __contact__ XML document representing the newly created contact.
#### `curl` sample
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"contact=
### modifyContact
This method allows a client to modify an existing contact in an address book. The _modifyContact_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| bookId | Yes | The unique identifier of the target address book. | N/A |
| contact | Yes | The XML document of the contact to modify. See above for details. Please note that the XML document must contain the _uid_ of the contact. | N/A |
#### Returned XML document
Upon success, this method returns a __contact__ XML document representing the modified contact.
#### `curl` sample
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"contact=
### removeContact
This method allows a client to remove a contact in an address book. The _removeContact_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| bookId | Yes | The unique identifier of the target address book. | N/A |
| id | Yes | The unique identifier of the contact to remove. | N/A |
#### Returned XML document
Upon success, this method returns a __contact__ XML document representing the removed contact.
#### `curl` sample
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"id=1262" https://OBM/ROOT/book/removeContact
### getContactFromId
This method allows a client to retrieve the details of a contact, knowing only its unique identifier. The _getContactFromId_ method accepts the following arguments:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| book | Yes | The type of address book to search. This parameter can be set to _contacts_ or _users_, depending on whether you're searching an OBM user or a contact. | None |
| id | Yes | The unique identifier of the contact to get the details of. | N/A |
#### Returned XML document
Upon success, this method returns a __contact__ XML document representing the removed contact.
#### `curl` sample
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"book=contacts" -d"id=1263" https://OBM/ROOT/book/getContactFromId
# Calendar management endpoint
### Common XML entities
#### CalendarInfo
A CalendarInfo entity gives information about a specific calendar. This information include:
* The _login_ (also known as the _uid_), _email_, _firstname_ and _lastname_ of the calendar owner.
* The rights that the caller has on the calendar.
A CalendarInfo entity is represented as an __info__ XML tag. This tag has the following structure:
| Tag | Data Type | Description | Occurrences |
| ----- |
| first | String | The firstname of the calendar owner. | 1 |
| last | String | The lastname of the calendar owner. | 1 |
| uid | String | The login of the calendar owner. | 1 |
| mail | String | The primary email of the calendar owner. | 1 |
| read | Boolean | Shows whether the caller has read access to the calendar. | 1 |
| write | Boolean | Shows whether the caller has write access to the calendar. | 1 |
Following is a sample of a _info_ XML tag:
#### Event
An Event is represented by an __event__ XML tag. This tag has the following structure:
...
...
...
...
...
| Tag | Data Type | Description | Occurrences |
| ----- |
| event | Event | The root tag. See below for a definition of the attributes of this tag. | N/A |
| timeupdate | Timestamp | The timestamp of the last modification date. | 1 |
| timecreate | Timestamp | The timestamp of the event creation date. | 1 |
| extId | String | The external id of the event. This is the key from the _client_ point of view. | 1 |
| opacity | OPAQUE/TRANSPARENT | The opacity of the event. OPAQUE means that the event sets attendees as _busy_ while TRANSPARENT doesn't. | 1 |
| title | String | The event title. | 1 |
| description | String | The event description. | O or 1 |
| ownerEmail | String | The email address of the event owner. | 1 |
| tz | String | The timezone that the event was created in. | 1 |
| date | Timestamp | The event date as a timestamp, in _UTC_ timezone. | 1 |
| duration | Integer | The event duration, in seconds. | 1 |
| category | String | The event category. See the _listCategories_ method to know how to fetch the available categories. | 0 or 1 |
| location | String | The event location. | 0 or 1 |
| alert | Integer | The defined event alert for the caller, in seconds. | 0 or 1 |
| priority | Integer | The event priority. This ranges from 1 (low) to (3) high and default to 2 (normal). | 0 or 1 |
| privacy | Integer | The event privacy level. Possible values are 0 (public), 1 (private) and 2 (confidential). | 1 |
| attendees | List of _attendee_ tags | Holds information about the attendees of the event. | 1 |
| attendee | None | Holds information about a single attendee of the event. See below for a definition of the attributes of this tag. | 1+ |
| recurrence | None | Holds information about the recurrence (if applicable) of the event. See below for a definition of the attributes of this tag. | 1 |
| exceptions | List of _exception_ tags | Holds information about the canceled occurrences of a recurrent event. | 1 |
| exception | Timestamp | Contains the recurrenceId of the cancelled occurrence. | 0+ |
| eventExceptions | List of _eventException_ tags | Holds information about the modified occurrences of a recurrent event. | 1 |
| eventException | Event | A complete _event_ tag, with the addition of the _recurrenceId_ tag. | 0+ |
| recurrenceId | Timestamp | The recurrence id of an exception to a recurrent event. This is actually the original date of the occurrence, as a timestamp. | 1 |
The table below lists the available attributes of the _event_ tag:
| Attribute | Data Type | Description | Required? | Default Value |
| ----- |
| type | String | Always VEVENT. This is there to support VTODO as well but this isn't in the scope of this specification. | Yes | N/A |
| allDay| Boolean | Whether the event is all day. | No | False |
| id | Integer | The internal id of the event in OBM. This is the key from the _server_ point of view. | No | N/A |
| isInternal | Boolean | Whether the event is internal (organized by an OBM user) or not. | False | True |
| sequence | Integer | The current sequence of the event. | No | 0 |
The table below lists the available attributes of the _attendee_ tag:
| Attribute | Data Type | Description | Required? | Default Value |
| ----- |
| displayName | String | The _display name_ (often simply "First Last") of the attendee. | No | None |
| email | String | The email address of the attendee. | Yes | N/A |
| isOrganizer | Boolean | Whether the attendee is the organizer of the event. | Yes | N/A |
| precent | Integer | Not used for event. This is there to support VTODO as well. | No | 0 |
| required | REQ/OPT | Whether the attendee is a required participant or not. | Yes | N/A |
| state | String | The participation state of the attendee. Possible values are _NEEDS-ACTION_, _ACCEPTED_ and _DECLINED_. | Yes | N/A |
The table below lists the available attributes of the _recurrence_ tag:
| Attribute | Data Type | Description | Required? | Default Value |
| ----- |
| kind | String | The kind of recurrence. Possible values are _none_, _daily_, _weekly_, _monthlybydate_, _monthlybyday_ and _yearly_. | Yes | N/A |
| days | String | For _weekly_ recurrent events, holds the week days that the event occurs on. See below for details. | No | N/A |
| freq | Integer | The frequence of the recurrence (also known as the interval). For instance, a frequence of 1 for a daily event means "every day". A frequence of 2 for a weekly event means "every two weeks". | No | N/A |
| end | Timestamp | The end of the recurrence, if any, as a timestamp. | No | N/A |
The _days_ attribute has a special format. It is composed of 7 characters (either _0_ or _1_), one for every week day, starting on sunday.
Here are some concrete examples:
* 0100000 means "occurs on monday"
* 1111111 means "occurs every day"
* 1010001 means "occurs on sunday, tuesday and saturday"
Following is a sample event with one cancelled occurence and a modified (delayed two hours) one:
f06746fba
### listCategories
This method allows a client to retrieve the list of available event categories in OBM. The _listCategories_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
#### Returned XML document
Upon success, this method returns a __categories__ XML document, which has the following structure:
...
| Tag | Data Type | Description | Occurrences |
| ----- |
| cat | Category | The _id_ attribute holds the internal ID of the category in OBM. The _label_ holds the name of the category. | N/A |
#### Sample XML document
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" http://OBM/ROOT/calendar/listCategories
### listCalendars
This method allows a client to retrieve the list of calendars that it has access to. The _listCalendars_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
#### Returned XML document
Upon success, this method returns a __calendar-infos__ XML document, which simply holds a list of __info__ XML tags (see _CalendarInfo_ for details).
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" http://OBM/ROOT/calendar/listCalendars
### getCalendarMetadata
This method allows a client to update calendar information on a list of calendars. This is useful when the client has subscribed to a list of calendars and it want to verify that rights haven't changed on server-side.
The _listCalendars_ method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| calendar | Yes | The email of the target calendar owner. This parameter can be passed multiple times. | N/A |
#### Returned XML document
Upon success, this method returns a __calendar-infos__ XML document, which simply holds a list of __info__ XML tags (see _CalendarInfo_ for details).
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" -d"calendar=usera@obm.domain" -d"calendar=userb@obm.domain" http://OBM/ROOT/calendar/getCalendarMetadata
### getSyncWithSortedChanges
This method allows a client to receive changes to calendars (it allows to be in-sync with the OBM backend). It supports incremental synchronization.
This method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| calendar | Yes | The email of the target calendar owner. | N/A |
| lastSync | No | The timestamp of the last successful synchronization done by the client. If given, only changes that occured after this date will be sent. | 0 |
| syncRangeAfter | No | If given, will only return changes to events occurring after this timestamp. This allows the client to provide an option to synchronize the whole calendar or only events newer than a given date. | 0 |
| syncRangeBefore | No | If given, will only return changes to events occurring before this timestamp. This allows the client to provide an option to synchronize the whole calendar or only events older than a given date. | 0 |
Using both `syncRangeBefore` and `syncRangeAfter` allows the client to get changes between between two dates.
#### Returned XML document
Upon success, this method returns a __calendar-changes__ XML document which has the following structure:
...
...
...
| Tag | Data Type | Description | Occurrences |
| ----- |
| calendar-changes | Timestamp | The root tag. The _lastSync_ attribute is the synchronization timestamp. This is typically stored by the client and sent back later on. | N/A |
| removed | List of _event_ tags | Holds a list of removed events. | 1 |
| removed/event | A shorthand of the _event_ tag | The _id_ attribute is the internal id of the event and _extId_ is the external event id. | 1+ |
| updated | List of _event_ tags | Holds a list of events that were modified. | 1 |
| updated/event | Event | A complete _event_ tag. | 1+ |
| participationChanges | List of _participation_ tags | Holds a list of participation changes. | 1 |
| participation | List of _attendee_ tags | Describes a participation change on an event. See below for the list of available attributes on this tag. | 1+ |
| participation/attendees/attendee | None | Holds the updated participation for an attendee. The _comment_ attribute holds an optional comment set when the attendee changed his participation. | 1+ |
The table below lists the available attributes of the _participation_ tag:
| Attribute | Data Type | Description | Required? | Default Value |
| ----- |
| id | Integer | The internal OBM id of the target event. | Yes | N/A |
| extId | String | The external id of the target event. | Yes | N/A |
| recurrenceId | String | If the event is an exception of a recurrent parent event, this holds the recurrenceId of the exception. The format of this attribute must be conforming to the ISO 8601 complete representation, basic format. | Yes | N/A |
#### Sample XML document
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" -d"calendar=usera@obm.domain" -d"lastSync=1373981725943" http://OBM/ROOT/calendar/getSyncWithSortedChanges
### storeEvent
This method allows a client to create or update an event in OBM. It accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| calendar | Yes | The email of the target calendar owner. | N/A |
| event | Yesy | An XML representation of the event to store. | N/A |
| notification | No | Whether notification emails should be sent for this creation/update. | False |
#### Returned XML Document
Upon success, this method returns an __event__ XML tag representing the created or modified event.
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" -d"calendar=usera@obm.domain" -d"event=
### removeEventByExtId
This method allows a client to remove an event. This method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| calendar | Yes | The email of the target calendar owner. | N/A |
| extId | Yes | The external id of the event to remove. | N/A |
| notification | No | Whether notification emails should be sent for this removal. | False |
| sequence | No | The current sequence of the event to remove. | 0 |
#### Returned XML document
Upon success, this method returns an __event__ XML tag representing the removed event.
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" -d"calendar=usera@obm.domain" -d"extId=4b168f39e3d0ba8b1a8e33847a8208c099f151fcdc" http://OBM/ROOT/calendar/removeEventByExtId
### changeParticipationState
This method allows a client to change the participation of a user to a given event. This method accepts the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| sid | Yes | A _session identifier_ obtained through the _doLogin_ method. | N/A |
| calendar | Yes | The email of the target calendar owner. The participation will be changed for this user. | N/A |
| extId | Yes | The external id of the target event. | N/A |
| state | Yes | The new participation state. Valid values are _NEEDS-ACTION_, _ACCEPTED_ and _DECLINED_. | N/A |
| notification | No | Whether notification emails should be sent for this update. | False |
| sequence | No | The current sequence of the target event. | 0 |
| recursive | No | Must be set to _true_ to update a simple event or a whole recurrent event. Must be _false_ to update a single exception to a recurrent event. | True |
| recurrenceId | No | Must be set when _recursive_ is false. This holds the recurrence id of the exception to update. The format of this parameter must be conforming to the ISO 8601 complete representation, basic format. | N/A |
#### Returned XML Entity
This method returns a Boolean value to indicate whether the call succeeded or not. This _result_ value is given as the following XML document:
#### Sample XML Document
#### `curl` sample
curl -sk -XPOST -d"sid=6e8b7955-f458-4024-ad29-bf6de2374c6f" -d"calendar=usera@obm.domain" -d"extId=4b168f39e3d0ba8b1a8e33847a8208c099f151fcdc" -d"state=DECLINED" http://OBM/ROOT/changeParticipationState
# Free/Busy endpoint
This endpoint supports a single operation: querying the free/busy of a user. It returns a user's availability one month ahead of the current date so that client can use this information to display possible conflicts when creating a meeting.
### Request
A free/busy request is made by issuing a *GET* HTTP request on _https://OBM/obm-sync/freebusy/
The request supports the following parameters:
| Name | Required? | Description | Default Value |
| ----- |
| organizer | No | The email address of the user creating the meeting. | N/A |
### Response
The endpoint might return the following HTTP codes:
| Code | Meaning | What client is expected to do |
| ----- |
| 404 | The target user doesn't exist in OBM. | This simply means that the user is not an OBM user. The client is expected to display a "No availability information" or similar message. |
| 403 | The target user doesn't publicly expose his/her availability. | OBM supports disabling publicly accessible free/busy. In this case, the client is expected to behave as if the user doesn't exist. |
| 200 | Everything went fine, see below for a description of the returned document. | Display the user's availability |
If the query succeeds (HTTP 200 is returned), the endpoint returns an _iCal_ VCALENDAR document containing a single VFREEBUSY component. See [this](http://tools.ietf.org/html/rfc5545#section-3.6.4) for the complete specification of this format and below for an example of such a document.
#### Sample returned iCal document
BEGIN:VCALENDAR
PRODID:-//Aliasource Groupe LINAGORA//OBM Calendar //FR
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:REPLY
BEGIN:VFREEBUSY
DTSTAMP:20131120T100521Z
ORGANIZER:mailto:user2@linagora.com
DTSTART:20131020T100521Z
DTEND:20131220T100521Z
ATTENDEE;CUTYPE=INDIVIDUAL;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=user1@domain.com;ROLE=OPT-PARTICIPANT:mailto:user1@domain.com
FREEBUSY;FBTYPE=BUSY:20131121T110000Z/20131121T130000Z
END:VFREEBUSY
END:VCALENDAR
The above document describes the availability of _user1@domain.com_ over a period ranging from 2013/10/20 10:05 (DTSTART property) to 2013/12/20 10:05 (DTEND property) for an event organized by _user2@domain.com_ (ORGANIZER property).
Each FREEBUSY line represents a period over which the user is busy. In the example, the user is busy on 2013/11/21 from 11:00 to 13:00, UTC time.
The user is considered available for the rest of the period.
#### `curl` sample
curl -sk https://OBM/obm-sync/freebusy/user1@domain.com?organizer=user2@domain.comΠΑΙΔΙΚΑ ΠΑΠΟΥΤΣΙΑ