The Hypertext Transfer Protocol (HTTP) is an application protocol that is the foundation of data communication for the web. UCWA leverages HTTP as an application protocol rather than as a transport protocol. The HTTP RFC defines the HTTP protocol in detail and contains several recommendations for clients and server components to follow. The UCWA protocol is based on the HTTP protocol but makes use of only a small subset of the features that are relevant for the API. For example, UCWA does not support HTTP verbs such as OPTIONS, HEAD, or TRACE, or many of the header names that are not relevant for the API. However, intermediate proxies and other edge servers might leverage other features of the HTTP protocol. The RFC provides more details about all of the verbs and headers that are defined for HTTP.
The UCWA API follows the REST model for manipulating resources. The HTTP verbs POST, GET, PUT, and DELETE are used to create, read, update and delete resources. The create, read, update, and delete operations are sometimes referred to as CRUD (Create, Read, Update, and Delete) operations.
The POST verb is often used on a collection resource to create a member resource of the collection. For example, a client application can send a POST request on the link for myOnlineMeetings resource to create a scheduled online meeting. It is also used to initiate processes, like sending an IM with sendMessage.
The GET verb is used to retrieve a resource.
The PUT verb is used to update the resource. The PUT operation requires the client to supply all of the properties (including those that are not understood by the client application) of the resource for the update operation to succeed. This is to ensure that new properties added in the future versions are preserved by older clients that do not understand them.
The DELETE verb is used to delete a resource. To delete a specific online meeting, the client application can use DELETE verb on the URL of the myOnlineMeeting resource instance.
UCWA makes use of several HTTP headers. A brief explanation of relevant headers is provided here. For more information, see the HTTP RFC.
- Accept Used by clients to state which format is preferred in the response body of an HTTP operation.
- Authorization Used by clients to provide credentials on each request.
- Content-Type: Used by client or server to indicate the format of the body of an HTTP operation.
- Etag Used to keep track of changes in resources and to prevent overwriting changes when performing a PUT. All UCWA resources require the playback of the Etag when performing a PUT.
- Expires Used by some resources to indicate how long the client should cache them.
- If-Match Used by clients when performing a PUT to prevent overwriting of changes to a resource. The resource's etag is provided as the value.
- WWW-Authenticate Used by the server to inform clients of how they can authenticate.
- X-MS-RequiresMinResourceVersion Used by the client to specify the minimum version of a resource it can understand.
- If-None-Match Used by clients in a GET request to reduce data transfer for resources that do not change often. The resource's etag is provided as the value.