\chapter{AtomPub Binding}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Overview
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview}

This binding is based upon the Atom (\hyperref[intro:rfc4287]{[RFC4287]}) and Atom Publishing Protocol (\hyperref[intro:rfc5023]{[RFC5023]}). Implementations of CMIS MUST be compliant with \hyperref[intro:rfc4287]{[RFC4287]} and \hyperref[intro:rfc5023]{[RFC5023]}.

In this binding, the client interacts with the repository by acquiring the service document. The client will request the service document by the URI provided by the vendor. The client will then choose a CMIS collection, and then start accessing the repository by following the references in the returned documents. 

This binding consists of a service document specifying at least CMIS service collections, Atom collections, feeds and entry documents. CMIS extends the Atom and AtomPub documents utilizing the Atom and AtomPub extension mechanism. CMIS also leverages link tags to specify additional resources related to the requested resource.

When requesting a resource, optional parameters may be specified to change default behavior via query parameters. 


\subsection{Namespaces}
\label{atom:namespaces}

This specification uses the following namespaces and prefixes when referring to XML or XML schema elements in the text or examples:
\begin{itemize}
	\item CMIS-Core: \path{http://docs.oasis-open.org/ns/cmis/core/200908/}\\
		Prefix: \texttt{cmis}
	\item CMIS-RestAtom: \path{http://docs.oasis-open.org/ns/cmis/restatom/200908/}\\
		Prefix: \texttt{cmisra}
	\item Atom : \path{http://www.w3.org/2005/Atom}\\
		Prefix: \texttt{atom}
	\item AtomPub: \path{http://www.w3.org/2007/app}\\
		Prefix: \texttt{app}
\end{itemize}


\subsection{Authentication}

Authentication SHOULD be handled by the transport protocol. Please see AtomPub \hyperref[intro:rfc5023]{[RFC5023]} section 14.

If the provided credentials are incorrect or unknown or entirely missing, a repository MAY return the HTTP status code 403 (Forbidden) instead of the HTTP status code 401 (Unauthorized). This may prevent attacks against the Browser Binding. See also section  \ref{browser:authentication}~\nameref{browser:authentication}.


\subsection{Response Formats}

The client can specify, in HTTP the Accept header, which formats are acceptable to the client. With this mechanism the client can choose which response format the CMIS implementation should respond with. The CMIS compliant implementation MUST support the appropriate Media Types specified in this document.


\subsection{Optional Arguments}

The binding supports adding optional parameters to CMIS resources to modify the default behavior. CMIS implementations MUST support arguments being specified as HTTP query string parameters.

Names and valid values for HTTP query string parameters are as described in the appropriate CMIS Service descriptions (see section  \ref{dm:services}~\nameref{dm:services}). Valid values of enumeration types are also represented in the CMIS Core XML Schema.


\subsection{Errors and Exceptions}

Exceptions MUST be mapped to the appropriate HTTP status code.

Repositories SHOULD provide sufficient information in the body of the HTTP response for a user to determine corrective action.

See section \ref{atom:statuscodes}~\nameref{atom:statuscodes} for more information.


\subsection{Renditions}
\label{atom:renditions}

Each rendition included in a CMIS AtomPub response is represented as an Atom link with a relationship alternate.\\ 

The following attributes SHOULD be included on the link element:
\begin{description}
	\item[href] URI to the rendition content stream
	\item[type] The Media Type of the rendition
	\item[cmisra:renditionKind] The Rendition Kind for the rendition
\end{description}

\hfill\\
The following attributes MAY be included:
\begin{description}
	\item[title] The filename (or name property if object) of rendition
	\item[length] The length of the rendition in bytes
\end{description}


\subsection{Content Streams}

The content stream for a document SHOULD be referenced by the content \texttt{src} attribute as well as the \texttt{edit-media} link relation.  
A CMIS Repository MAY use different URIs for both content \texttt{src} attribute and the \texttt{edit-media} link relation for the same content stream.\\

The following attributes SHOULD be included on the link element:

\begin{description}
	\item[href] URI to the content stream
	\item[type] The Media Type of the content stream
\end{description}


\subsection{Paging of Feeds}

For paging, please see the AtomPub RFC.  CMIS leverages first, next, previous, and last link relations to express paging.

If the repository can include the number of items (\texttt{numItems} in CMIS Domain Model) in a feed, then the repository SHOULD include the \texttt{cmisra:numItems} extension element in the feed.


\subsection{Services not Exposed}
\label{atom:servicesnotexposed}

The following services are not exposed in this binding:
\begin{sloppypar}
\begin{itemize}
	\item \cmisservicelink{getRenditions}: This is exposed as part of \cmisservicelink{getObject}.
	\item \cmisservicelink{getProperties}: This is exposed as part of \cmisservicelink{getObject}.
	\item \cmisservicelink{getPropertiesOfLatestVersion}: This is exposed as part of \cmisservicelink{getObjectOfLatestVersion}.
	\item \cmisservicelink{createDocumentFromSource}: This is not exposed in this binding except as the client saving the resource and resubmitting it without the \texttt{cmis:objectId}.
	\item Adding and removing ACEs on Create or CheckIn operations: This is not possible with the AtomPub binding. The Create or CheckIn operation must be performed first. Then the dependent resource, ACL, must be retrieved and updated.  
	\item \cmisservicelink{setContentStream}: This does not return the new object id and change token as specified by the domain model.  This is not possible without introducing a new HTTP header.
	\item \cmisservicelink{deleteContentStream}: This does not return the new object id and change token as specified by the domain model.  This is not possible without introducing a new HTTP header.
	\item \cmisservicelink{checkOut}: This does not return whether or not content was copied.  This is not possible without introducing a new HTTP header. Clients may check content related properties such as the \texttt{cmis:contentStreamLength} property if the Private Working Copy has a content stream.
	\item \cmisservicelink{deleteTree}: This does not return which objects have not been deleted. If the deletion of a folder fails, the client can call \cmisservicelink{getChildren} or \cmisservicelink{getDescendants} to determine which objects could not been deleted. 
\end{itemize}
\end{sloppypar}

\subsubsection{removePolicy}

This service is exposed from the domain model in the AtomPub binding. However, it is not as straightforward.  To remove a policy from an object, one must do:
\begin{itemize}
	\item Get the object.
	\item Fetch the policies collection of the object.
	\item Walk through the feed and find the policy object where \texttt{cmis:objectId} == policy id to remove.
	\item Get the self link of this policy object.
	\item Perform a DELETE on this URL.
\end{itemize}

This is also the only case in the AtomPub Binding where an URI in a collection (policies) is specific to that collection.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% HTTP
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{HTTP}


\subsection{HTTP Range}

Repositories MAY support HTTP Range requests on content streams.


\subsection{HTTP OPTIONS Method}

The repository MAY support the HTTP OPTIONS method on all the resources defined in this specification.  If the repository supports OPTIONS, then the repository MUST at least return the HTTP methods specified for that resource in the Allow header.


\subsection{HTTP Status Codes}
\label{atom:statuscodes}

Please see the HTTP specification for more information on the HTTP status codes.  These are provided as guidance from the HTTP specification.  If any conflict arises, the HTTP specification is authoritative.


\subsubsection{General CMIS Exceptions}

The following listing defines the HTTP status codes that repositories MUST return for the various common exceptions defined in CMIS Domain Model. 

\begin{tabular}{ll}
	\textbf{CMIS Services Exception} & \textbf{HTTP Status Code}\\
	\textit{General Exceptions} &\\
	\cmisexceptionlink{invalidArgument} & 400\\
	\cmisexceptionlink{notSupported} & 405\\
	\cmisexceptionlink{objectNotFound} & 404\\
	\cmisexceptionlink{permissionDenied} & 403\\
	\cmisexceptionlink{runtime} & 500\\
	\textit{Specific Exceptions} &\\
	\cmisexceptionlink{constraint} & 409\\
	\cmisexceptionlink{contentAlreadyExists} & 409\\
	\cmisexceptionlink{filterNotValid} & 400\\
	\cmisexceptionlink{nameConstraintViolation} & 409\\
	\cmisexceptionlink{storage} & 500\\
	\cmisexceptionlink{streamNotSupported} & 403\\
	\cmisexceptionlink{updateConflict} & 409\\
	\cmisexceptionlink{versioning} & 409\\
\end{tabular}


\subsubsection{Notable HTTP Status Codes}

\begin{description}
	\item[415 Unsupported Media Type]\hfill\\ 
		When a document is POST'ed to a collection that does not support the media type of the document, this status code MUST be returned
	\item[422 Unprocessable Entity] (Defined in \hyperref[intro:rfc4918]{[RFC4918]} Section 11.2)\hfill\\ 
		When a request has been POST'ed but cannot be processed, this status code MUST be returned.
\end{description}

Please see \hyperref[intro:rfc2616]{[RFC2616]} Section 10 for more information.


\section{Media Types}

CMIS introduces new media types for:
\begin{itemize}
	\item a CMIS Query document (\texttt{application/cmisquery+xml})
	\item a CMIS AllowableActions document (\texttt{application/cmisallowableactions+xml})
	\item an Atom document (Entry or Feed) with any CMIS Markup (\texttt{application/cmisatom+xml})
	\item an Atom Feed document with CMIS Hierarchy extensions (\texttt{application/cmistree+xml})
	\item a CMIS ACL document (\texttt{application/cmisacl+xml})
\end{itemize}

\hfill\\
In addition to those media types specified by CMIS, CMIS also leverages these media types:
\begin{itemize}
	\item AtomPub Service (\texttt{application/atomsvc+xml})
	\item Atom Entry (\texttt{application/atom+xml;type=entry})
	\item Atom Feed (\texttt{application/atom+xml;type=feed})
\end{itemize}


\subsection{CMIS Atom}

\begin{cmisatompubmedia}
Media Type: & \texttt{application/cmisatom+xml}\\
Starting tag: & \texttt{atom:feed} or \texttt{atom:entry}\\
Type Parameters: & \texttt{type}: the semantics of the type parameter MUST be the same as the media type parameter for Atom documents.
\end{cmisatompubmedia}

This allows clients to differentiate between repositories that require Atom media type with CMIS extensions (\texttt{application/cmisatom+xml}) for creation and repositories that allow generic Atom media type without CMIS extensions (\texttt{application/atom+xml}). 

This is only used for CMIS repositories to advertise what media types are accepted for adding to a collection (e.g., creating resources in a collection).  As such CMIS does not require specifying whether an Atom feed has CMIS markup.  It is included to be consistent with the Atom media type.

All feeds and entries from a CMIS repository MUST utilize the Atom media type for exposing Atom resources.  Please see the individual resources for more information on the media type.  This provides the interoperability with Atom clients.

%\cmisatompubxml{Example}{cmisatom.xml}
\cmisexample{atompub/getObject}


\subsection{CMIS Query}

\begin{cmisatompubmedia}
Media Type: & \texttt{application/cmisquery+xml}\\
Starting tag: & \texttt{cmis:query}\\
\end{cmisatompubmedia}

This document contains the representation of a query to be executed in a CMIS repository.

%\cmisatompubxml{Example}{cmisquery.xml}
\cmisexample{atompub/doQuery}


\subsection{CMIS Allowable Actions}

\begin{cmisatompubmedia}
Media Type: & \texttt{application/cmisallowableactions+xml}\\
Starting tag: & \texttt{cmis:allowableActions}\\
\end{cmisatompubmedia}

This document contains the representation of the allowable actions the user may perform on the referenced object.

%\cmisatompubxml{Example}{cmisallowableactions.xml}
\cmisexample{atompub/getAllowableActions}


\subsection{CMIS Tree}
\label{atom:cmistree}

\begin{cmisatompubmedia}
Media Type: & \texttt{application/cmistree+xml}\\
Starting tag: & \texttt{atom:feed}\\
\end{cmisatompubmedia}

This document is an Atom feed (\texttt{application/atom+xml;type=feed}) with CMIS markup to nest a hierarchy.

Please see section \ref{atom:hierarchicalatomentries}~\nameref{atom:hierarchicalatomentries}.

%\cmisatompubxml{Example}{cmistree.xml}
\cmisexample{atompub/getDescendants}


Note: This media type is used on links with relation \texttt{down} (see section \ref{atom:hierarchynavigationlink}~\nameref{atom:hierarchynavigationlink}).  When the individual resources are returned by the CMIS repository they will use the Atom media type (\texttt{application/atom+xml})


\subsection{CMIS ACL}

\begin{cmisatompubmedia}
Media Type: & \texttt{application/cmisacl+xml}\\
Starting tag: & \texttt{cmis:acl}\\
\end{cmisatompubmedia}

This document specifies an Access Control List based on the schema in CMIS Domain Model.

%\cmisatompubxml{Example}{cmisacl.xml}
\cmisexample{atompub/getAcl}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Atom Extensions for CMIS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Atom Extensions for CMIS}


\subsection{Atom Element Extensions}


\subsubsection{AtomPub Workspace}


\paragraph{cmisra:collectionType}

This element is included inside the \texttt{app:collection} element. This specifies the CMIS collection type.


\paragraph{cmisra:repositoryInfo}

This element is included inside the \texttt{app:workspace} element. This specifies information about the CMIS repository.


\paragraph{cmis:uritemplate}

This element is included inside the \texttt{app:workspace} element. This specifies information about URI templates


\subsubsection{Atom Feed}


\paragraph{cmisra:numItems}

This element is included inside the \texttt{atom:feed} element. This specifies the number of items in the feed.


\subsubsection{Atom Entry}


\paragraph{cmisra:children}

This element is included inside the \texttt{atom:entry} element. This includes the children of the Atom entry.  This element MUST include an \texttt{atom:feed} element.


\paragraph{cmisra:object}

This element is included inside the \texttt{atom:entry} element for CMIS document, folder, relationship, policy, and item objects. This specifies the CMIS object information for the Atom entry.


\paragraph{cmisra:pathSegment}

This element is included inside the \texttt{atom:entry} element. This specifies the pathSegment for this object in the folder representing the feed.


\paragraph{cmisra:relativePathSegment}

This element is included inside the \texttt{atom:entry} element. This specifies the relative pathSegment for the object in that particular folder.  This MUST be used only inside an object parents feed.


\paragraph{cmisra:type}

This element is included inside the \texttt{atom:entry} element for CMIS Type Definitions. This specifies the type definition the Atom entry represents.


\paragraph{cmisra:content}

This element specifies the content of the \texttt{atom:entry} element. The content is base64 encoded in the \texttt{base64} element.  The elements of a \texttt{cmisra:content} element are:
\begin{description}
	\item[cmisra:mediaType] This contains the media type of the content as described by \hyperref[intro:rfc4288]{[RFC4288]}.
	\item[cmisra:base64] This contains the base64 content of the file
\end{description}

This element MUST take precedence over \texttt{atom:content} on submission of an Atom entry to a repository.  

A repository MUST use the \texttt{atom:content} element to return back to the client the content of the document.

Note: This is required when the client has an XML document stored that might not be well formed and thus would not be able to be included inside \texttt{atom:content} element.


\paragraph{cmisra:bulkUpdate}

This element is included inside the \texttt{atom:entry} element. It specifics bulk update data.

See the \cmisservicelink{bulkUpdateProperties} service for details.


\subsection{Attributes}

These attributes are in the CMIS RestAtom namespace (\texttt{cmisra}).


\subsubsection{cmisra:id}

This attribute is used on the \texttt{atom:link} element to specify the CMIS id of the resource.  This attribute SHOULD be on all link relations that point to a CMIS object.

This attribute MAY also be on \texttt{cmisra:type}.  The value of the attribute on \texttt{cmis:type} MUST be the same as the type definition id.

\cmisatompubxml{Example}{cmisraid.xml}


\subsubsection{cmisra:renditionKind}

This attribute is used on the \texttt{atom:link} element with relation alternate to specify the renditionKind of the resource.  This attribute SHOULD be on all link elements with relation alternate that are a CMIS rendition.

\cmisatompubxml{Example}{cmisrarendition.xml}


\subsection{CMIS Link Relations}

The listing below outlines the different link relation types in CMIS.  This is in addition to the link relations specified by Atom and Atom Publishing Protocol.  The registry for link relations is located at \url{http://www.iana.org/assignments/link-relations/link-relations.xhtml}.

The link element with a specified relation MUST be included if client can perform the operation.  The repository SHOULD omit the link relation if the operation is not available.  The operation may not be available due to a variety of reasons such as access control, administrative policies, or other mechanisms.

Links may have the following attribute in addition to the ones specified by Atom and Atom Publishing Protocol:
\begin{description}
	\item[cmisra:id] Specifies the CMIS Id of the resource referenced by the link. Repositories SHOULD include this attribute for elements such as \texttt{atom:link} that point to CMIS resources that have an id. 
\end{description}


\subsubsection{Existing Link Relations}

Existing link relations should be used where appropriate by the implementation.  In addition, the following link relations are leveraged for the CMIS specification: 

\begin{cmisatompublink}{self}
	\item This link relation provides the URI to retrieve this resource again.
	\item Service: The appropriate service that generated the Atom entry or feed.
	\item Resources: All except AllowableActions, ACL and Content Streams
\end{cmisatompublink}

\begin{cmisatompublink}{service}
	\item The service link relation when provided on a CMIS resource MUST point to an AtomPub service document with only one workspace element.  This workspace element MUST represent the repository containing that resource.
	\item Media Type: \texttt{application/atomsvc+xml}
	\item Resources: All except AllowableActions, ACL and Content Streams
\end{cmisatompublink}

\begin{cmisatompublink}{describedby}
	\item When used on a CMIS resource, this link relation MUST point to an Atom entry that describes the type of that resource. 
	\item Service: \cmisservicelink{getTypeDefinition} on specified object
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS document, CMIS folder, CMIS relationship, CMIS policy, CMIS item objects and CMIS types
\end{cmisatompublink}

\begin{cmisatompublink}{via}
	\item When used on an Atom feed document, this link relation MUST point to the Atom entry representing the CMIS resource from whom this feed is derived.  
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: All CMIS Feeds and Collections
\end{cmisatompublink}

\begin{cmisatompublink}{edit-media}
	\item When used on a CMIS document resource, this link relation MUST point to the URI for content stream of the CMIS document.  This URI MUST be used to set or delete the content stream.  This URI MAY be used to retrieve the content stream for the document.
	\item Service: \cmisservicelink{setContentStream} (PUT), \cmisservicelink{appendContentStream} (PUT), \cmisservicelink{deleteContentStream} (DELETE)
	\item Media Type: Specific to resource
	\item Resources: CMIS document 
\end{cmisatompublink}

\begin{cmisatompublink}{edit}
	\item When used on a CMIS resource, this link relation MUST provide an URI that can be used with the HTTP PUT method to modify the \texttt{atom:entry} for the CMIS resource.
	\item Service: \cmisservicelink{getObject} (GET), \cmisservicelink{updateProperties} (PUT)
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS documents, CMIS folders, CMIS relationships, CMIS policies, and CMIS items
\end{cmisatompublink}

\begin{cmisatompublink}{alternate}
	\item This is used to express renditions on a CMIS resource.  See section \ref{dm:renditions}~\nameref{dm:renditions}.
	\item Service: \cmisservicelink{getContentStream} for specified rendition
	\item Resources: CMIS documents and folders
\end{cmisatompublink}

\begin{cmisatompublink}{first}
	\item This is used for paging.  Please see the AtomPub specification.
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: All Feeds
\end{cmisatompublink}

\begin{cmisatompublink}{previous}
	\item This is used for paging.  Please see the AtomPub specification.
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: All Feeds
\end{cmisatompublink}

\begin{cmisatompublink}{next}
	\item This is used for paging.  Please see the AtomPub specification.
	\item Media Type:\texttt{application/atom+xml;type=feed}
	\item Resources: All Feeds
\end{cmisatompublink}

\begin{cmisatompublink}{last}
	\item This is used for paging.  Please see the AtomPub specification.
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: All Feeds
\end{cmisatompublink}

Please see \url{http://www.iana.org/assignments/link-relations/link-relations.xhtml} for more information on these link relations.


\subsubsection{Hierarchy Navigation Internet Draft Link Relations}
\label{atom:hierarchynavigationlink}

CMIS leverages the following link relations:

\begin{cmisatompublink}{up}
	\item Service: \cmisservicelink{getFolderParent}, \cmisservicelink{getObjectParents}, \cmisservicelink{getTypeDefinition}, \cmisservicelink{getObject} 
	\item Media Type: \texttt{application/atom+xml;type=feed}, \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS documents, folders,  policies, items, type definitions, folder children, folder descendants, folder tree, type children, type descendants
	\item This link relation MUST not be included on CMIS base type definitions or the CMIS root folder
\end{cmisatompublink}

\begin{cmisatompublink}{down}
	\item Service: \cmisservicelink{getChildren}, \cmisservicelink{getDescendants}, \cmisservicelink{getTypeChildren}, \cmisservicelink{getTypeDescendants} 
	\item Media Type: 
	\begin{itemize*}
		\item For children: \texttt{application/atom+xml;type=feed}
		\item For descendants: \texttt{application/cmistree+xml}
		\item The descendants feed resource when retrieved from the CMIS repository will use the Atom Feed Media Type (\texttt{application/atom+xml;type=feed})
	\end{itemize*}
	\item Resources: CMIS folders, types
\end{cmisatompublink}


\subsubsection{Versioning Internet Draft Link Relations}

CMIS leverages the following link relations from the Internet Draft:

\begin{cmisatompublink}{version-history}
	\item Service: \cmisservicelink{getAllVersions}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: CMIS documents
\end{cmisatompublink}

\begin{cmisatompublink}{current-version}
	\item Service: \cmisservicelink{getObjectOfLatestVersion} (major == FALSE)
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS documents
\end{cmisatompublink}

\begin{cmisatompublink}{working-copy}
	\item Service: \cmisservicelink{getObject} for Private Working Copy specified by \texttt{cmis:versionSeriesCheckedOutId} property
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS documents if a PWC exists
\end{cmisatompublink}


\subsubsection{CMIS Specific Link Relations}

CMIS defines the following link relations:

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions}
	\item This link relation MUST point to a resource containing a CMIS AllowableActions document for the CMIS resource containing this link relation.
	\item Service: \cmisservicelink{getAllowableActions}
	\item Media Type: \texttt{application/cmisallowableactions+xml}
	\item Resources: CMIS documents, folders, policies, relationships, and items
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/relationships}
	\item This link relation MUST point to a resource containing an Atom feed of CMIS relationship resources for the CMIS resource containing this link relation.
	\item Service: \cmisservicelink{getObjectRelationships}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: CMIS documents, folders, policies, and items
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/source}
	\item When used on a CMIS relationship resource, this link relation MUST point to an Atom entry document for the CMIS Resource specified by the \texttt{cmis:sourceId} property on the relationship.
	\item Source Link on Relationship
	\item Service: \cmisservicelink{getObject}
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS relationships 
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/target}
	\item When used on a CMIS relationship resource, this link relation MUST point to an Atom entry document for the CMIS Resource specified by the \texttt{cmis:targetId} property on the relationship.
	\item Target Link on Relationship
	\item Service: \cmisservicelink{getObject}
	\item Media Type: \texttt{application/atom+xml;type=entry}
	\item Resources: CMIS relationships
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/policies}
	\item This link relation MUST point to a resource containing an Atom feed of CMIS policy resources for the CMIS resource containing this link relation.
	\item Service: \cmisservicelink{getAppliedPolicies}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: CMIS documents, folders, relationships, policies, and items
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/acl}
	\item This link relation MUST point to a resource containing a CMIS ACL document for the CMIS resource containing this link relation.
	\item Service: \cmisservicelink{getACL}
	\item Media Type: \texttt{application/cmisacl+xml}
	\item Resources: CMIS documents, folders, relationships, policies, and items that are securable
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/changes}
	\item This link relation MUST point to an Atom feed containing the set of changes.
	\item Service: \cmisservicelink{getContentChanges}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: AtomPub Workspace Element in Service document
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/foldertree}
	\item Used in AtomPub Service document  to identify the folder tree for a specified folder.
	\item Service: \cmisservicelink{getFolderTree}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: CMIS folders, also used in AtomPub Service document for root folder
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/typedescendants}
	\item Used in AtomPub Service document to identify the base types descendants.
	\item Service: \cmisservicelink{getTypeDescendants}
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: AtomPub Workspace Element in Service document
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/rootdescendants}
	\item Used in AtomPub Service document to identify the root folder descendants.
	\item Service: \cmisservicelink{getDescendants} for root folder
	\item Media Type: \texttt{application/atom+xml;type=feed}
	\item Resources: AtomPub Workspace Element in Service document
\end{cmisatompublink}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Atom Resources
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Atom Resources}

For all Atom resources used in this specification, the following MUST be followed:


\subsection{Feeds}

Any feed MUST be a valid Atom Feed document and conform to the guidelines below for CMIS objects:

\begin{itemize}
	\item \texttt{atom:updated} SHOULD be the latest time the folder or its contents was updated. If unknown by the underlying repository, it MUST be the current time.
	\item \texttt{atom:author/atom:name} MUST be the CMIS property \texttt{cmis:createdBy}.
	\item \texttt{atom:title} MUST be the CMIS property \texttt{cmis:name}.
	\item The \texttt{atom:link} with relation \texttt{self} MUST be generated to return the URI of the feed. If paging or any other mechanism is used to filter, sort, or change the representation of the feed, the URI MUST point back a resource with the same representation.
	\item A feed SHOULD contain the element \texttt{app:collection}, describing the appropriate media types supported for creation of new entries in the feed
	\item \texttt{atom:id} SHOULD be derived from \texttt{cmis:objectId}. This id MUST be compliant with atom's specification and be a valid URI. 
	\item Feeds MAY be paged via the link relations specified in AtomPub. If more items are available than contained in the feed, then a link with the relation next MUST be included in the feed.
\end{itemize}


Any feed MUST be a valid Atom Feed document and conform to the guidelines below for CMIS types:

\begin{itemize}
	\item \texttt{atom:updated} SHOULD be the latest time type definition was updated. If unknown by the underlying repository, it MUST be the current time.
	\item \texttt{atom:author/atom:name} is repository specific.
	\item \texttt{atom:title} MUST be the displayName attribute of the CMIS type definition. 
	\item The \texttt{atom:link} with relation self MUST be generated to return the IRI of the feed.
	\item \texttt{atom:id} SHOULD be derived from the id attribute of the CMIS type definition. This id MUST be compliant with atom's specification and be a valid URI. 
	\item Feeds MAY be paged via the link relations specified in AtomPub.  If more items are available than contained in the feed, then a link with the relation next MUST be included in the feed.
\end{itemize}

If on the root type, all fields are repository specific.

Ordering of entries in a feed is repository-specific if the \texttt{orderBy} argument is not specified. If the \texttt{orderBy} argument is specified, the order of the entries in the feed SHOULD conform to the ordering specified by the \texttt{orderBy} argument. If a repository only supports a certain number of \texttt{orderBy} properties, it SHOULD ignore all additional properties.


\subsection{Entries}

At any point where an Atom document of type Entry is sent or returned, it must be a valid Atom Entry document and conform to the guidelines below for a cmis object:

\begin{itemize}
	\item \texttt{atom:title} MUST be the \texttt{cmis:name} property.
	\item \texttt{app:edited} MUST be \texttt{cmis:lastModificationDate}.
	\item \texttt{atom:updated} MUST be \texttt{cmis:lastModificationDate}.
	\item \texttt{atom:published} MUST be \texttt{cmis:creationDate}.
	\item \texttt{atom:author/atom:name} MUST be \texttt{cmis:createdBy}.
	\item \texttt{atom:summary} SHOULD be \texttt{cmis:description}.
	\item All CMIS properties MUST be exposed in CMIS \texttt{cmis:properties} elements even if they are duplicated in an Atom element.
	\item \texttt{atom:id} SHOULD be derived from \texttt{cmis:objectId}. This id MUST be compliant with atom's specification and be a valid IRI.
\end{itemize}

\begin{cmisdescription}{For documents that support content streams}
The repository SHOULD use the \texttt{atom:content/src} attribute to point to the content stream. The client SHOULD use \texttt{cmisra:content} if the content is not well-formed or would have trouble fitting inside an \texttt{atom:content} element.  The repository MUST use the \texttt{cmisra:content} element if provided by the client over the \texttt{atom:content} element.
\end{cmisdescription}

\begin{cmisdescription}{Other objects}
(Folders, relationships, policies, items, and other document types that do not support content streams, etc.)

The repository SHOULD provide an \texttt{atom:summary} element and no \texttt{atom:content} element in order to comply with the Atom specification. Any value in the content field MUST be ignored if the Atom entry represents a non-document object by the CMIS repository when the Atom entry is POST'ed to a collection or sent to the repository via a PUT. 
\end{cmisdescription}

When POSTing an Atom Document, the Atom elements MUST take precedence over the corresponding writable CMIS property.  For example, \texttt{atom:title} will overwrite \texttt{cmis:name}.


At any point where an Atom document of CMIS type is sent or returned, it must be a valid Atom Entry document and conform to the guidelines below for a CMIS type definition:

\begin{itemize}
	\item \texttt{atom:title} MUST be the \texttt{cmis:displayName}
	\item The repository SHOULD populate the \texttt{atom:summary} tag with text that best represents a summary of the object.  For example, the type description if available.
\end{itemize}

Any Atom element that is not specified is repository-specific.


\subsubsection{Hierarchical Atom Entries}
\label{atom:hierarchicalatomentries}

The repository SHOULD NOT provide any links to hierarchical objects if those capabilities are not supported with the exception of \cmisservicelink{getTypeDescendants} which is required.

For Atom entries that are hierarchical such as Folder Trees or Descendants, the repository MUST populate a \texttt{cmisra:children} element in the \texttt{atom:entry} with the enclosing feed of its direct children.  This pattern continues until the depth is satisfied.

The \texttt{cmisra:children} element MUST include an \texttt{atom:feed} element that contains the children entries of this resource.

If an entry does not contain \texttt{cmisra:children} element, then the entry MAY have children even though it is not represented in the Atom entry.

%%\cmisatompubxml{Example}{hierarchical.xml}

Please see section \ref{atom:cmistree}~\nameref{atom:cmistree}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Resources Overview
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Resources Overview}
\begin{longtable}{p{0.1in}p{2.4in}p{2.4in}c}
	& \textbf{Service} & \textbf{Resource} & \textbf{HTTP Method} \\
	\hline
 	\endhead

	\hline
	\multirow{8}{*}{\begin{sideways}Repository\end{sideways}}
  	& \cmisservicelink{getRepositories} & \nameref{atom:servicedocument} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getRepositoryInfo} & \nameref{atom:servicedocument} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getTypeChildren} & \nameref{atom:typechildrencollection} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getTypeDescendants} & \nameref{atom:typedescendantsfeed} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getTypeDefinition} & \nameref{atom:typeentry} & GET \\
	\cline{2-4}
  	& \cmisservicelink{createType} & \nameref{atom:typechildrencollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{updateType} & \nameref{atom:typeentry} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{deleteType} & \nameref{atom:typeentry} & DELETE \\
	\hline
	
	\multirow{6}{*}{\begin{sideways}Navigation\end{sideways}}
  	& \cmisservicelink{getChildren} & \nameref{atom:folderchildrencollection} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getDescendants} & \nameref{atom:folderdescendantsfeed} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getFolderTree} &  \nameref{atom:foldertreefeed} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getFolderParent} & \nameref{atom:folderentry}  & GET \\
	\cline{2-4}
  	& \cmisservicelink{getObjectParents} & \nameref{atom:objectparentsfeed} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getCheckedOutDocs} & \nameref{atom:checkedoutcollection} & GET \\
	\hline

	\multirow{17}{*}{\begin{sideways}Object\end{sideways}}
  	& \cmisservicelink{createDocument} & \nameref{atom:folderchildrencollection} or \newline \nameref{atom:unfiledcollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{createDocumentFromSource} & See \ref{atom:servicesnotexposed}~\nameref{atom:servicesnotexposed} &  \\
	\cline{2-4}
  	& \cmisservicelink{createFolder} & \nameref{atom:folderchildrencollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{createRelationship} & \nameref{atom:relationshipscollection}& POST \\
	\cline{2-4}
  	& \cmisservicelink{createPolicy} & \nameref{atom:folderchildrencollection} or \newline \nameref{atom:unfiledcollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{getAllowableActions} & \nameref{atom:allowableactionsresource} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getObject} & \nameref{atom:documententry} or \newline
		\nameref{atom:pwcentry} or \newline 
		\nameref{atom:folderentry} or \newline 
		\nameref{atom:relationshipentry} or \newline 
		\nameref{atom:policyentry} or \newline 
		\nameref{atom:itementry} or \newline 
		\texttt{objectbyid} URI template & GET \\
	\cline{2-4}
  	& \cmisservicelink{getProperties} & See \ref{atom:servicesnotexposed}~\nameref{atom:servicesnotexposed} & \\
	\cline{2-4}
  	& \cmisservicelink{getObjectByPath} & \texttt{objectbypath} URI template & GET \\
	\cline{2-4}
  	& \cmisservicelink{getContentStream} & \nameref{atom:contentstream} & GET \\
	\cline{2-4}
  	& \cmisservicelink{getRenditions} & See \ref{atom:servicesnotexposed}~\nameref{atom:servicesnotexposed}  &  \\
	\cline{2-4}
  	& \cmisservicelink{updateProperties} & \nameref{atom:documententry} or \newline
		\nameref{atom:pwcentry} or \newline 
		\nameref{atom:folderentry} or \newline 
		\nameref{atom:relationshipentry} or \newline 
		\nameref{atom:policyentry} or \newline 
		\nameref{atom:itementry} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{bulkUpdateProperties} & \nameref{atom:bulkupdatecollection} & POST  \\
	\cline{2-4}
  	& \cmisservicelink{moveObject} & \nameref{atom:folderchildrencollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{deleteObject} & \nameref{atom:documententry} or \newline
		\nameref{atom:folderentry} or \newline 
		\nameref{atom:relationshipentry} or \newline 
		\nameref{atom:policyentry} or \newline 
		\nameref{atom:itementry} & DELETE \\
	\cline{2-4}
  	& \cmisservicelink{deleteTree} & \nameref{atom:foldertreefeed} & DELETE\\
	\cline{2-4}
  	& \cmisservicelink{setContentStream} & \nameref{atom:contentstream} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{appendContentStream} & \nameref{atom:contentstream} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{deleteContentStream} & \nameref{atom:contentstream} & DELETE \\
	\hline

	\multirow{2}{*}{\begin{sideways}Multi\end{sideways}}
  	& \cmisservicelink{addObjectToFolder} & \nameref{atom:folderchildrencollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{removeObjectFromFolder} & \nameref{atom:unfiledcollection} & POST \\
	\hline

	\multirow{2}{*}{\begin{sideways}Disc\end{sideways}}
  	& \cmisservicelink{query} & \nameref{atom:querycollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{getContentChanges} & \nameref{atom:changesfeed} & GET \\
	\hline

	\multirow{6}{*}{\begin{sideways}Versioning\end{sideways}}
  	& \cmisservicelink{checkOut} & \nameref{atom:checkedoutcollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{cancelCheckOut} & \nameref{atom:pwcentry}  & DELETE \\
	\cline{2-4}
  	& \cmisservicelink{checkIn} & \nameref{atom:pwcentry}  & PUT \\
	\cline{2-4}
  	& \cmisservicelink{getObjectOfLatestVersion} & \nameref{atom:documententry} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{getPropertiesOfLatestVersion} & See \ref{atom:servicesnotexposed}~\nameref{atom:servicesnotexposed} &  \\
	\cline{2-4}
  	& \cmisservicelink{getAllVersions} & \nameref{atom:allversionsfeed}  & GET \\
	\hline

	\multirow{1}{*}{\begin{sideways}Rel\end{sideways}}
  	& \cmisservicelink{getObjectRelationships} & \nameref{atom:relationshipscollection} & GET \\
	\hline

	\multirow{3}{*}{\begin{sideways}Policy\end{sideways}}
  	& \cmisservicelink{applyPolicy} & \nameref{atom:policiescollection} & POST \\
	\cline{2-4}
  	& \cmisservicelink{removePolicy} & \nameref{atom:policiescollection}  & DELETE \\
	\cline{2-4}
  	& \cmisservicelink{getAppliedPolicies} & \nameref{atom:policiescollection}  & GET \\
	\hline

	\multirow{2}{*}{\begin{sideways}ACL\end{sideways}}
  	& \cmisservicelink{applyACL} & \nameref{atom:aclresource} & PUT \\
	\cline{2-4}
  	& \cmisservicelink{getACL} & \nameref{atom:aclresource} & GET \\
	\hline
\end{longtable}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% AtomPub Service Document
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{AtomPub Service Document}
\label{atom:servicedocument}

The AtomPub Service Document contains the set of repositories that are available.  

How the client will get the initial AtomPub (APP) service document or the URI for the service document is repository specific.  Examples are via URI, or loading the service document from disk.  



The service document will also be available from Atom Entry and Atom Feed documents via a link relationship \texttt{service}.  That AtomPub service document MUST then only contain one workspace element which MUST be the workspace representing the repository containing the Atom Entry or Atom Feed document.


\subsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getRepositories}
	\item \cmisservicelink{getRepositoryInfo}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Arguments}
	\item[repositoryId] (optional)\newline
	\begin{itemize}
		\item This query parameter allows a client to specify a different repository than the one that is referenced by the URI.  
		\item If specified, the repository MUST return the AtomPub services document for the specified repository if that repository exists.
		\item If not specified, the repository MUST return the service document for the repository that is referenced by URI.
	\end{itemize}
\end{cmisatompubdescs}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atomsvc+xml}
\end{cmisatompubitems}


Each repository is mapped to a \texttt{app:workspace} element in the AtomPub Service document. A workspace element MUST have a collection element for each of following collections. Each collection MUST also contain a \texttt{cmisra:collectionType} element with the given value.

\begin{itemize}
	\item Root Folder Children Collection: Root folder of the repository
	\begin{itemize*}
		\item 'root' for the children collection of the root folder
		\item \texttt{cmisra:collectiontype} = 'root'
	\end{itemize*}
	\item Types Children Collection: Collection containing the base types in the repository
	\begin{itemize*}
		\item 'types' for the children collection
		\item \texttt{cmisra:collectiontype} = 'types'
	\end{itemize*}
\end{itemize}

The workspace element SHOULD also contain these collections if the repository supports this functionality:

\begin{itemize}
	\item CheckedOut collection: collection containing all checked out documents user can see
	\begin{itemize*}
		\item \texttt{cmisra:collectiontype} = 'checkedout'
	\end{itemize*}
	\item Query collection: Collection for posting queries to be executed
	\begin{itemize*}
		\item \texttt{cmisra:collectiontype} = 'query'
	\end{itemize*}
	\item Unfiled collection: Collection for posting documents to be unfiled; read can be disabled
	\begin{itemize*}
		\item \texttt{cmisra:collectiontype} = 'unfiled'
	\end{itemize*}
	\item Bulk update collection: Collection for posting property updates for multiple objects at once
	\begin{itemize*}
		\item \texttt{cmisra:collectiontype} = 'update'
	\end{itemize*}
\end{itemize}

\hfill \\

The workspace element MUST also contain the following link element with the relation:

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/typedescendants}
	\item This link relation points to the \nameref{atom:typedescendantsfeed} for the base types in the repository.
\end{cmisatompublink}

The workspace element MUST contain the following link elements of the following relations for those services which are supported by the repository:

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/foldertree}
	\item This link relation points to the \nameref{atom:foldertreefeed}  for the root folder.
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/rootdescendants}
	\item This link relation points to the \nameref{atom:folderdescendantsfeed}  for the root folder.
\end{cmisatompublink}

\begin{cmisatompublink}{http://docs.oasis-open.org/ns/cmis/link/200908/changes}
	\item This link relation points to the \nameref{atom:changesfeed} for the repository.
\end{cmisatompublink}

The workspace element may include \texttt{app:collection} elements for the collections that represent folders in the repository.  However, an alternative approach, especially for a repository with many folders, is to not enumerate those collections here, but include the \texttt{app:collection} element per \hyperref[intro:rfc5023]{[RFC5023]} in the Atom Feed document. 

The repository MUST include the URI templates in the workspace elements.


\subsubsection{URI Templates}

CMIS defines the following URI templates:
\begin{itemize*}
	\item \texttt{objectbyid}
	\item \texttt{objectbypath}
	\item \texttt{query}
	\item \texttt{typebyid}
\end{itemize*}

Repositories MUST provide the following URI templates:
\begin{itemize*}
	\item \texttt{objectbyid}
	\item \texttt{objectbypath}
	\item \texttt{typebyid}
\end{itemize*}

Repositories MUST provide the URI template \texttt{query} if the repository supports query.

Repositories MAY extend that set of templates.  Those URI template types will be repository specific.  Repositories MAY have more than one entry per URI template type if the entries have different media types.

URI templates are simple replacement of the template parameter with the specified value. If a client does not want to specify a value for some of these variables, then the client MUST substitute an empty string for the variable.


For example, if the URI template that supports the variable \texttt{\{id\}} is:
\begin{verbatim}
http://example.com/rep1/getbyid/{id}
\end{verbatim}

If the client wants to find the entry for an object with an id of 'obj\_1' then the URI would be:
\begin{verbatim}
http://example.com/rep1/getbyid/obj_1
\end{verbatim}

URI Templates MUST only be used with HTTP GET.

Arguments that are substituted for URI template parameters MUST be percent escaped according to \hyperref[intro:rfc3986]{[RFC3986]}.  Please see that RFC for more information. 

All variables MUST be in the template.


\paragraph{Structure of URI Templates}

\cmisatompubxml{Structure}{uritemplate-structure.xml}

\cmisatompubxml{Example}{uritemplate-example.xml}


\paragraph{Object By Id}

This URI template provides a method for creating an URI that directly accesses an Atom entry representing document, folder, policy, relationship, or item objects.  See section \ref{atom:resources}~\nameref{atom:resources} for more information.\\

Type: \texttt{objectbyid}

Media Type: \texttt{application/atom+xml;type=entry}

Service: \cmisservicelink{getObject} or \cmisservicelink{getObjectOfLatestVersion}\\

Variables that are supported by the template:

\begin{description}
	\item[\{id\}] maps to service parameter \texttt{objectId}.
	\item[\{filter\}] maps to service parameter \texttt{filter}.
	\item[\{includeAllowableActions\}] maps to service parameter \texttt{includeAllowableActions}.
	\item[\{includePolicyIds\}] maps to service parameter \texttt{includePolicyIds}.
	\item[\{includeRelationships\}] maps to service parameter \texttt{includeRelationships}.
	\item[\{includeACL\}] maps to service parameter \texttt{includeACL}.
	\item[\{renditionFilter\}] maps to service parameter \texttt{renditionFilter}.
	\item[\{returnVersion\}]
	\begin{itemize*}
		\item If no value is present or the value is 'this', \cmisservicelink{getObject} MUST be called. 
		\item If the value is 'latest' \cmisservicelink{getObjectOfLatestVersion} MUST be called with the parameter \texttt{major} set to FALSE.
		\item If the value is 'latestmajor' \cmisservicelink{getObjectOfLatestVersion} MUST be called with the parameter \texttt{major} set to TRUE.
	\end{itemize*}
\end{description}

\cmisatompubxml{Example}{uritemplate-objectbyid.xml}


\paragraph{Object By Path}

This URI template provides a method for creating an URI that directly accesses an Atom entry representing document, folder, policy, relationship, or item objects. See section \ref{atom:resources}~\nameref{atom:resources} for more information.\\

Type: \texttt{objectbyid}

Media Type: \texttt{application/atom+xml;type=entry}

Service: \cmisservicelink{getObjectByPath}\\

Variables that are supported by the template:

\begin{description}
	\item[\{path\}] maps to service parameter \texttt{path}.
	\item[\{filter\}] maps to service parameter \texttt{filter}.
	\item[\{includeAllowableActions\}] maps to service parameter \texttt{includeAllowableActions}.
	\item[\{includePolicyIds\}] maps to service parameter \texttt{includePolicyIds}.
	\item[\{includeRelationships\}] maps to service parameter \texttt{includeRelationships}.
	\item[\{includeACL\}] maps to service parameter \texttt{includeACL}.
	\item[\{renditionFilter\}] maps to service parameter \texttt{renditionFilter}.
\end{description}

\cmisatompubxml{Example}{uritemplate-objectbypath.xml}


\paragraph{Query}

This URI template provides a method for creating an URI that performs a query.\\

Type: \texttt{query}

Media Type: \texttt{application/atom+xml;type=feed}

Service: \cmisservicelink{query}\\

Variables that are supported by the template:

\begin{description}
	\item[\{q\}] maps to service parameter \texttt{statement}.
	\item[\{searchAllVersions\}] maps to service parameter \texttt{searchAllVersions}.
	\item[\{maxItems\}] maps to service parameter \texttt{maxItems}.
	\item[\{skipCount\}] maps to service parameter \texttt{skipCount}.
	\item[\{includeAllowableActions\}] maps to service parameter \texttt{includeAllowableActions}.
	\item[\{includeRelationships\}] maps to service parameter \texttt{includeRelationships}.
	\item[\{renditionFilter\}] maps to service parameter \texttt{renditionFilter}.
\end{description}

\cmisatompubxml{Example}{uritemplate-query.xml}


\paragraph{Type By Id}

This URI template provides a method for creating an URI that directly accesses a type definition.\\

Type: \texttt{typebyid}

Media Type: \texttt{application/atom+xml;type=entry}

Service: \cmisservicelink{getTypeDefinition}\\

Variables that are supported by the template:

\begin{description}
	\item[\{id\}] maps to service parameter \texttt{typeId}.
\end{description}

\cmisatompubxml{Example}{uritemplate-typebyid.xml}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Service Collections
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Service Collections}

These are the collections that are included on an AtomPub Service document in the workspace element.

For any HTTP verb not specified on a resource, each implementation MAY chose to implement that HTTP verb in a repository-specific manner.


%%
\subsection{Root Folder Collection}
\label{atom:rootfoldercollection}

This collection provides access to the children of the root folder. Please see section \ref{atom:folderchildrencollection}~\nameref{atom:folderchildrencollection}.


%%
\subsection{Query Collection}
\label{atom:querycollection}

This is a collection for processing queries. If the implementation supports GET on this collection, then the implementation SHOULD at least return a feed consisting of zero or more Atom entries. These Atom entries should represent persisted objects related to query such as persisted queries, long running queries or search templates.


\subsubsection{HTTP POST}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{query}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support CMIS query document (\texttt{application/cmisquery+xml})
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

The feed returned MUST contain a set of Atom entries representing the result set from the query.  

The Atom entries should contain the bare minimum necessary for Atom compliance \hyperref[intro:rfc4287]{[RFC4287]}.  The Atom entries MUST contain the CMIS extension element (\texttt{cmisra:object}) containing the properties specified by the query in the select clause of the query statement.

If all the selected properties can be mapped to the same type reference, then the repository MAY include additional information in the Atom entry.

Please see \hyperref[intro:rfc5023]{[RFC5023]} Section 5.3.

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
	\item \texttt{Content-Location}
\end{cmisatompubitems}

Upon submission (creation) of a query document, a response must be returned with a Location header representing the feed for that query.  If the query cannot be performed and an Atom feed returned, the repository MUST return the appropriate HTTP status code.  In addition, the server SHOULD return the feed directly.  If the server does so, the server SHOULD also return the Content-Location header. 

%\cmisatompubhttp{Example client request}{query-request.txt}

%\cmisatompubhttp{Example server response}{query-response.txt}

\cmisexample{atompub/doQuery}


%%
\subsection{Checked Out Collection}
\label{atom:checkedoutcollection}

\subsubsection{HTTP GET}

This is a collection described in the service document that contains the Private Working Copies (PWCs) of the checked-out documents in the repository.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getCheckedOutDocs}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item folderId
	\item maxItems
	\item skipCount
	\item renditionFilter
	\item includeAllowableActions
	\item includeRelationships
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


\subsubsection{HTTP POST}

When an Atom Entry is POSTed to this collection, the document will be checked out. A \texttt{Content-Location} header MUST be returned containing the location of the Private Working Copy. The newly created \nameref{atom:pwcentry} MUST be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{checkOut}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		\texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Content-Location}
\end{cmisatompubitems}


\cmisexample{atompub/checkOut}

%\cmisatompubhttp{Example client request}{checkout-request.txt}

%\cmisatompubhttp{Example server response}{checkout-response.txt}


%%
\subsection{Unfiled Collection}
\label{atom:unfiledcollection}

This is a collection described in the service document to manage unfiled document, policy, and item objects.

\subsubsection{HTTP POST}

If this is called with an existing object, the object will be removed from all folders in the repository by default.  If the optional argument \texttt{removeFrom} is specified, the object will only be removed from that folder.

If this is called with an entry that doesn't have an object id, a new, unfiled object will be created.

The removed or newly created \nameref{atom:documententry}, \nameref{atom:policyentry}, or \nameref{atom:itementry}  MUST be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{removeObjectFromFolder}
	\item \cmisservicelink{createDocument}
	\item \cmisservicelink{createPolicy}
	\item \cmisservicelink{createItem}
\end{cmisatompubitems}

If the Atom Entry POSTed has a valid \texttt{cmis:objectId} property, \cmisservicelink{removeObjectFromFolder} will be performed. If the Atom Entry POSTed has no \texttt{cmis:objectId} property, the value of the \texttt{cmis:objectTypeId} property decides if \cmisservicelink{createDocument}, \cmisservicelink{createPolicy}, or \cmisservicelink{createItem} will be performed. In all other cases (invalid object id, the object does not exist, the object is not in that folder, the object type id is invalid, the base type is neither \texttt{cmis:document} nor \texttt{cmis:policy} nor \texttt{cmis:item}, etc.) the appropriate HTTP status code MUST be returned. See also  \ref{atom:folderchildrencollection}~\nameref{atom:folderchildrencollection}. 

\begin{cmisatompubitems}{Arguments}
	\item removeFrom
	\item versioningState
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}

\cmisexample{atompub/removeObjectFromFolder}


%%
\subsection{Type Children Collection}
\label{atom:typechildrencollection}

This is a collection described in the service document that contains the types in the repository under the specified parent type.  If no parent type is specified, then the base types are returned in the feed.  This feed does not include any nesting and is a flat feed.

\subsubsection{HTTP GET}

This feed contains a set of Atom entries for each child type definition.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getTypeChildren}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item typeId
	\item includePropertyDefinitions
	\item maxItems
	\item skipCount
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the type definition entry whose children represent this feed.
	\item[down] Points to the Atom feed document representing the descendants collection for this same type.\\ Media Type: \texttt{application/cmistree+xml}
	\item[up] Points to the parent type definition. If this is a children feed for a base object type, this link is not present.
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


\cmisexample{atompub/getTypeChildren}


\subsubsection{HTTP POST}

This creates a new object-type.

The server MUST return the appropriate HTTP status code if the specified parent type doesn't match this collection.

The created object-type entry MUST be returned.


\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{createType}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS type extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}



%%
\subsection{Bulk Update Collection}
\label{atom:bulkupdatecollection}

This collection is used for bulk updates.

\subsubsection{HTTP POST}

The POSTed entry MUST include a CMIS Atom extension element \texttt{cmisra:bulkUpdate}. It contains the set of objects that should be updated, the new property values and secondary type modifications.


\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{bulkUpdateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry} 
\end{cmisatompubitems}


The returned object entries MUST follow these rules:
\begin{itemize}
	\item The property \texttt{cmis:objectId} MUST be set. The value MUST be the original object id even if the repository created a new version and therefore generated a new object id. New object ids are not exposed by this binding.
	\item The property \texttt{cmis:changeToken} MUST be set if the repository supports change tokens.
	\item All other properties are optional.
\end{itemize}


\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Collections
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Collections}

For any HTTP verb not specified on a resource, each implementation MAY chose to implement that HTTP verb in a repository-specific manner.


%%
\subsection{Relationships Collection}
\label{atom:relationshipscollection}

This collection manages relationships.


\subsubsection{HTTP GET}

This collection contains the set of relationships available (either source or target or both) from a specific item such as a document, folder, policy, or item. 

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObjectRelationships}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item typeId
	\item includeSubRelationshipTypes
	\item relationshipDirection
	\item maxItems
	\item skipCount
	\item filter
	\item includeAllowableActions
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository. The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


\subsubsection{HTTP POST}

When an Atom entry with CMIS markup is POSTed to this collection, if that Atom entry represents a new CMIS relationship, then that relationship will be created.

The server MUST return the appropriate HTTP status code if the source is different than the sourceId or target different than the targetId for the source and targets specified in this collection.

The server MUST return the appropriate status code if the \texttt{cmis:objectTypeId} is not specified.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{createRelationship}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}

% \cmisatompubhttp{Example client request}{relationships-request.txt}

% \cmisatompubhttp{Example server response}{relationships-response.txt}


%%
\subsection{Folder Children Collection}
\label{atom:folderchildrencollection}

This collection managed folder children.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getChildren}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item maxItems
	\item skipCount
	\item filter
	\item includeAllowableActions
	\item includeRelationships
	\item renditionFilter\\ If specified, renditions will be returned as links with relation \texttt{alternate}.
	\item orderBy
	\item includePathSegment
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the Atom entry of the folder generating this collection.
	\item[up] Points to the Atom entry document for this folder’s parent. If the root folder, this link relation MUST NOT be included.\\ Media Type: \texttt{application/atom+xml;type=entry}
	\item[down] Points to the Atom feed document representing the descendants feed. This is represented as a feed with CMIS hierarchy extensions. If a repository does not support \texttt{capabilityGetDescendants}, then this link SHOULD NOT be included.\\ Media Type: \texttt{application/cmistree+xml}
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/foldertree] Points to the folder tree for this folder. This is represented as a feed with CMIS hierarchy extensions. If a repository does not support \texttt{capabilityGetFolderTree}, then this link SHOULD NOT be included.\\ Media Type: \texttt{application/atom+xml;type=feed}
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
	\item \texttt{cmisra:pathSegment} inside \texttt{atom:entry} if includePathSegment is TRUE
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\cmisexample{atompub/getChildren}


\subsubsection{HTTP POST}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{createDocument}
	\item \cmisservicelink{createFolder}
	\item \cmisservicelink{createPolicy}
	\item \cmisservicelink{createItem}
	\item \cmisservicelink{moveObject}
	\item \cmisservicelink{addObjectToFolder}
\end{cmisatompubitems}


\begin{cmisdescription}{POSTing an Atom Entry document with CMIS markup}
If the Atom entry has a CMIS property \texttt{cmis:objectId} that is valid for the repository, the object (document, folder, policy, or item) will be added to the folder.  

When an object is added to the folder, in repositories that do not support multi-filing it will be removed from the previous folder and the operation treated as move.  If the repository supports multiple folders, it will be added to the new folder.  
If the optional argument sourceFolderId is specified, then the object will be removed from the folder specified.
\end{cmisdescription}


\begin{cmisdescription}{Creating a new CMIS object in that folder}
If the \texttt{cmis:objectId} property is missing, the object will be created and then added to the folder.  If the \texttt{cmis:objectId} property is present but not a valid object Id, the repository MUST return the appropriate HTTP status code.\newline

For documents:
\begin{itemize}
	\item If Content Stream is not provided and it is required by the type definition, the repository MUST return the appropriate HTTP status code.  
	\item Content Streams MAY be provided by any of the following mechanisms:
	\begin{itemize}
		\item As part of the Atom entry via the \texttt{src} attribute on the content element. Implementers MAY support external references to content. If the URI in the \texttt{src} attribute is not reachable, then an appropriate HTTP status code should be returned.
		\item As part of the Atom entry inlining via the AtomPub \texttt{content} element. Please see the AtomPub specification \hyperref[intro:rfc5023]{[RFC5023]} for the processing model of the content element.
		\item If the \texttt{cmisra:content} is provided by the client inside the \texttt{atom:entry}, the  \texttt{cmisra:content} element MUST take precedence over the  \texttt{atom:content} element. This element  \texttt{cmisra:content} contains the content base64 encoded.
		\item At a later time by replacing the \texttt{edit-media} link with a new content.
	\end{itemize}
	\item The optional argument versioningState MAY specify additional versioning behavior such as checkin.
\end{itemize}
\end{cmisdescription}


\begin{cmisdescription}{POSTing other document formats (AtomPub)}
The behavior is repository specific when a non Atom entry or an atom document without the CMIS elements is posted to a folder collection. 

For example, the repository MAY auto-create a document with a specific type (document) the client could edit.  

If the repository does not support this scenario or another exception occurs, then the repository MUST return the appropriate HTTP status code.
\end{cmisdescription}


\begin{cmisatompubdescs}{Arguments}
	\item[sourceFolderId] This parameter indicates the folder from which the object shall be moved from to the current specified folder.  This parameter is not allowed for create operations.\\
If specified \cmisservicelink{moveObject} will be performed. If not specified, \cmisservicelink{addObjectToFolder} will be performed.
	\item[versioningState] This optional argument MAY specify additional versioning behavior such as checkIn as major or minor. Please see CMIS Domain Model for more information on this parameter.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}

%\cmisatompubhttp{Example client request -  moveObject}{children-move-request.txt}

%\cmisatompubhttp{Example server response -  moveObject}{children-move-response.txt}

%\cmisatompubhttp{Example client request -  createDocument}{children-create-request.txt}

%\cmisatompubhttp{Example server response -  createDocument}{children-create-response.txt}

\cmisexample{atompub/createDocument}


\subsubsection{HTTP DELETE}

See HTTP DELETE description in section \ref{atom:foldertreefeed}~\nameref{atom:foldertreefeed}.


%%
\subsection{Policies Collection}
\label{atom:policiescollection}

This collection managed policies applied to an object.


\subsubsection{HTTP GET}

The policy entries displayed here are specific to the object generating this collection.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getAppliedPolicies}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the Atom entry of the resource generating this collection.
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


\subsubsection{HTTP POST}

When an Atom Entry representing a Policy is posted to this collection, the policy will be applied to the object.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{applyPolicy} (to object representing this collection of policies)
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
	\item MAY support other media type
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 201 Created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}

%\cmisatompubhttp{Example client request}{policies-request.txt}

%\cmisatompubhttp{Example server response}{policies-response.txt}


\subsubsection{HTTP DELETE}

This is the only collection where the URI's of the objects in the collection MUST be specific to that collection.  A DELETE on the policy object in the collection is a removal of the policy from the object NOT a deletion of the policy object itself.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{removePolicy}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Feeds
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Feeds}

For any HTTP verb not specified on a resource, each implementation MAY chose to implement that HTTP verb in a repository-specific manner.


%%
\subsection{Object Parents Feed}
\label{atom:objectparentsfeed}

This is the set of parents for a specific object.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObjectParents}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item includeAllowableActions
	\item includeRelationships
	\item renditionFilter
	\item includeRelativePathSegment
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
	\item \texttt{cmisra:relativePathSegment} inside \texttt{atom:entry} if includeRelativePathSegment is TRUE
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\cmisexample{atompub/getObjectParents}

%\cmisatompubhttp{Example server response}{parents-response.txt}


%%
\subsection{Changes Feed}
\label{atom:changesfeed}

This is a link relationship described in the service document that contains the changes in the repository in the workspace element. The link relation pointing to this feed is \path{http://docs.oasis-open.org/ns/cmis/link/200908/changes}.

The ChangeLog Token is specified in the URI specified by the paging link notations.  Through this binding it is not possible to retrieve the ChangeLog Token from the URIs.

\subsubsection{HTTP GET}

This feed MUST be ordered from oldest first to newest.

If the next changes does not exist yet, the link relation next MAY be available. If the next link relation is not available, the client should revisit the feed in the future and look for new items and the next link relation.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getContentChanges}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item maxItems
	\item includeACL
	\item includePolicyIds
	\item includeProperties
	\item changeLogToken\\ 
		If this parameter is specified, start the changes from the specified token.  The changeLogToken is embedded in the paging link relations for normal iteration through the change list.
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[first, next, previous, last] Paging link relations as appropriate. ChangeLogToken is incorporated into the URI specified by the next link relation.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


\cmisexample{atompub/getContentChanges}

%\cmisatompubhttp{Example server response}{changes-response.txt}


%%
\subsection{Folder Descendants Feed}
\label{atom:folderdescendantsfeed}

This is a hierarchical feed comprising items under a specified folder to a specified depth.  This is available via the link relation down with the \texttt{application/cmistree+xml} media type. Please see section \ref{atom:hierarchicalatomentries}~\nameref{atom:hierarchicalatomentries} for more information on format.

If a repository does not support \texttt{capabilityGetDescendants}, then these resources SHOULD NOT be exposed.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getDescendants}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item depth
	\item includeAllowableActions
	\item includeRelationships
	\item renditionFilter
	\item includePathSegment
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the Atom entry of the folder generating this collection.
	\item[up] Points to the Atom entry document for this folder's parent. If the root folder, this link relation MUST NOT be included.\\ Media Type: \texttt{application/atom+xml;type=entry}
	\item[down] Points to the Atom feed document representing the children feed for this same folder.\\ Media Type: \texttt{application/atom+xml;type=feed}\\Since this is the descendants, the descendants link SHOULD NOT be included. 
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/foldertree] Points to the folder tree for this folder. If a repository does not support \texttt{capabilityGetFolderTree}, then this link SHOULD NOT be included.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
	\item \texttt{cmisra:pathSegment} inside \texttt{atom:entry} if includePathSegment is TRUE
	\item \texttt{cmisra:children} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{descendants-response.txt}
\cmisexample{atompub/getDescendants}


\subsubsection{HTTP DELETE}

See HTTP DELETE description in section \ref{atom:foldertreefeed}~\nameref{atom:foldertreefeed}.
 

%%
\subsection{Folder Tree Feed}
\label{atom:foldertreefeed}

This is a hierarchical feed comprising all the folders under a specified folder.  This is available via the link relation foldertree with media type \texttt{application/atom+xml;type=feed}.  Please see section \ref{atom:hierarchicalatomentries}~\nameref{atom:hierarchicalatomentries} for more information on format.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getFolderTree}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item depth
	\item includeAllowableActions
	\item includeRelationships
	\item renditionFilter
	\item includePathSegment
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the Atom entry of the folder generating this collection.
	\item[up] Points to the Atom entry document for this folder's parent. If the root folder, this link relation MUST not be included.\\ Media Type: \texttt{application/atom+xml;type=entry}
	\item[down] Points to the Atom feed document representing the children feed for this same folder.\\ Media Type: \texttt{application/atom+xml;type=feed}
	\item[down] Points to the descendants feed of the same folder. If a repository does not support \texttt{capabilityGetDescendants}, then this link SHOULD NOT be included.\\ Media Type: \texttt{application/cmistree+xml}
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
	\item \texttt{cmisra:pathSegment} inside \texttt{atom:entry} if includePathSegment is TRUE
	\item \texttt{cmisra:children} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{foldertree-response.txt}


\subsubsection{HTTP DELETE}

This deletes the folder and all sub-folders. 

If the DELETE method does not delete all items, invoking GET with infinite depth on the \nameref{atom:folderdescendantsfeed} will return the items not deleted.  Subsequent DELETE methods can be invoked on this URI.

Note: If the repository does not implement the \nameref{atom:folderdescendantsfeed}, there is no mechanism to identify the resources that were not removed.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteTree}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item continueOnFailure
	\item unfileObjects
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK, if successful.  Body contains entity describing the status
	\item 202 Accepted, if accepted but deletion not yet taking place
	\item 204 No Content, if successful with no content
	\item 401 Unauthorized, if not authenticated
	\item 403 Forbidden, if permission is denied
	\item 500 Internal Server Error.  The body SHOULD contain an entity describing the status
\end{cmisatompubitems}


%%
\subsection{All Versions Feed}
\label{atom:allversionsfeed}

This is a feed comprised of all the versions of the given document. The feed MUST contain the newest versions at the beginning of the feed.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getAllVersions}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item filter
	\item includeAllowableActions
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the Atom entry of the resource generating this collection.
	\item[first, next, previous, last] Paging link relations as appropriate.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:object} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{allversions-response.txt}
\cmisexample{atompub/getAllVersions}


%%
\subsection{Type Descendants Feed}
\label{atom:typedescendantsfeed}

This is a feed described in the service document that contains all the types under a specific type in the repository to a specific depth.  If no parent type is specified, then the base types and their descendants are returned in the feed which is equivalent to all types in the repository if depth is infinite.  The link relation is \path{http://docs.oasis-open.org/ns/cmis/link/200908/typedescendants}.

Types are nested using the CMIS hierarchy extension. Please see section \ref{atom:hierarchicalatomentries}~\nameref{atom:hierarchicalatomentries} for more information on format.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getTypeDescendants}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item typeId
	\item depth
	\item includePropertyDefinitions
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=feed}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[via] Points to the type definition whose descendants represent this feed.  This link is not present if no parent type is specified.
	\item[up] Points to the parent type definition. If this is a descendants feed for a base object type, this link is not present.
	\item[down] Points to the children feed for the same type.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MAY be included inside the Atom feed}
	\item \texttt{cmisra:numItems}
\end{cmisatompubitems}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entries}
	\item \texttt{cmisra:type} inside \texttt{atom:entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{typedescendants-response.txt}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Resources
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Resources}
\label{atom:resources}

For any HTTP verb not specified on a resource,each implementation MAY chose to implement that HTTP verb in a repository-specific manner.

%%
\subsection{Type Entry}
\label{atom:typeentry}

This represents a type definition in the repository. This is enclosed as an Atom entry.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getTypeDefinition}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[up] Points to the parent type as Atom entry if applicable.
	\item[down] Points to the children feed of this type as Atom feed if applicable.\\ Media Type: \texttt{application/atom+xml;type=feed}
	\item[down] Points to the descendants feed of this type as Atom feed if applicable.\\ Media Type: \texttt{application/cmistree+xml}
	\item[describedby] Points to the type definition Atom entry of the base type of this type definition.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:type}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{typeentry-response.txt}
\cmisexample{atompub/getTypeDefinition}

\subsubsection{HTTP PUT}

This updates the object-type.

The updated object-type entry MUST be returned. See section \ref{dm:typemutability}~\nameref{dm:typemutability} for details.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateType}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item MUST support Atom Entry documents with CMIS type extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This deletes the object-type.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteType}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{Document Entry}
\label{atom:documententry}

This is a CMIS Document instance.

\subsubsection{HTTP GET}

This returns the document.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
	\item \cmisservicelink{getObjectOfLatestVersion}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item returnVersion\\Used to differentiate between \cmisservicelink{getObject} and \cmisservicelink{getObjectOfLatestVersion}. Valid values are are described by the schema element \texttt{cmisra:enumReturnVersion}. If not specified, return the version specified by the URI.
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
	\item renditionFilter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[self] Points to an URI that returns the Atom entry for this document.  Please see Atom for more information.
	\item[edit] Points to an URI that accepts PUT of Atom entry.  Please see AtomPub for more information.
	\item[up] Points to the atom feed containing the set of parents.  If there is only one parent, the repository MAY point this link relation directly to the Atom entry of the parent.
	\item[version-history] Points to Atom feed containing the versions of this document. If the document is not versionable, this link relation may not be on the resource.
	\item[current-version] Points to the latest version of the document. Uses query parameter 'returnVersion' and enumReturnVersion. If this version is the current-version, this link relation MAY not be on the resource.
	\item[edit-media] Same as \cmisservicelink{setContentStream}.  Allows updating the content stream on this document. Please see AtomPub for more information.
	\item[working-copy] Points to the private working copy if it exists.
	\item[describedby] Points to the type definition as an Atom entry for the type of this document.
	\item[alternate] This is used to identify the renditions available for the specified object.  Please see section \ref{atom:renditions}~\nameref{atom:renditions}.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/relationships] Points to the relationships feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/policies] Points to the policies feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to the ACL document for this object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{documententry-response.txt}

\cmisexample{atompub/getObject}


\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If readwrite properties are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This removes the document or all versions of the version series.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item allVersions
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}

\cmisexample{atompub/deleteObject}


%%
\subsection{PWC Entry}
\label{atom:pwcentry}

This is the private working copy of the document (checkedout version of document).

\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
	\item renditionFilter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}	
	\item[self] Points to the URI to retrieve this Atom entry.  Please see Atom for more information.
	\item[edit] Points to the URI to update this Atom entry via PUT.  Please see AtomPub for more information.
	\item[up] Points to the Atom feed containing the set of parents.  If there is only one parent, the repository MAY point this link relation directly to the Atom entry of the parent.
	\item[version-history] Points to Atom feed containing the versions of this document.
	\item[edit-media] Same as \cmisservicelink{setContentStream}.  Allows updating the content stream on this document. Please see AtomPub for more information.
	\item[via] Atom entry that created this PWC.
	\item[describedby] Points to the type definition as an Atom entry for the type of this PWC entry.
	\item[alternate] This is used to identify the renditions available for the specified object.  Please see section \ref{atom:renditions}~\nameref{atom:renditions}.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/relationships] Points to the relationships feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/policies] Points to the policies feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to ACL document for this object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{pwcentry-response.txt}


\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If modifiable properties (whencheckedout or readwrite) are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
	\item \cmisservicelink{checkIn}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item checkinComment
	\item major
	\item checkin\\
		Used to differentiate between \cmisservicelink{updateProperties} or \cmisservicelink{checkIn} services. If TRUE, execute \cmisservicelink{checkIn} service.
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}

\cmisexample{atompub/checkIn}


\subsubsection{HTTP DELETE}

This removes the document entry, in this case, cancels the check out.  The PWC will be removed.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{cancelCheckOut}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}



%%
\subsection{Folder Entry}
\label{atom:folderentry}

This is a CMIS Folder instance.  


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
	\item renditionFilter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}	
	\item[self] Points to an URI that returns the Atom entry for this folder.  Please see Atom for more information.
	\item[edit] Points to an URI that accepts PUT of Atom entry.  Please see AtomPub for more information.
	\item[down] Points to the feed document representing the children feed for this same folder.\\ Media Type: \texttt{application/atom+xml;type=feed}
	\item[down] Points to the descendants feed of the same folder.\\ Media Type: \texttt{application/cmistree+xml}	
	\item[up] Points Atom entry of the parent. If the root folder, this link will not be present.
	\item[describedby] Points to the type definition as an Atom entry for the type of this folder.
	\item[alternate] This is used to identify the renditions available for the specified object.  Please see section \ref{atom:renditions}~\nameref{atom:renditions}.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/relationships] Points to the relationships feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/policies] Points to the policies feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to ACL document for this object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{folderentry-response.txt}



\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If readwrite properties are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\cmisexample{atompub/updateProperties}


\subsubsection{HTTP DELETE}

This removes the folder from the repository. This is deletion of the folder only and not any contained objects.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{Relationship Entry}
\label{atom:relationshipentry}

This is a CMIS relationship instance.  These objects are exposed via 'relationships' link type.


\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[self] Points to an URI that returns the Atom entry for this relationship.  Please see Atom for more information.
	\item[edit] Points to an URI that accepts PUT of Atom entry.  Please see AtomPub for more information.
	\item[describedby] Points to the type definition as an Atom entry for the type of this relationship.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/policies] Points to the policies feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to the ACL document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/source] Points to the Atom entry of the source object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/target] Points to the Atom entry of the target object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{relationshipentry-response.txt}



\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If readwrite properties are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This removes the relationship from the repository.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{Policy Entry}
\label{atom:policyentry}

This is a CMIS policy instance.

\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[self] Points to an URI that returns the Atom entry for this policy.  Please see Atom for more information.
	\item[edit] Points to an URI that accepts PUT of Atom entry.  Please see AtomPub for more information.
	\item[describedby] Points to the type definition as an Atom entry for the type of this policy.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/relationships] Points to the relationships feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to the ACL document for this object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{policyentry-response.txt}


\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If readwrite properties are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This removes the policy from the repository. If this policy entry was discovered through a policy collection on an object, then \cmisservicelink{removePolicy} is performed rather than \cmisservicelink{deleteObject} on the policy itself.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{Item Entry}
\label{atom:itementry}

This is a CMIS item instance.

\subsubsection{HTTP GET}

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item includeAllowableActions
	\item includeRelationships
	\item includePolicyIds
	\item includeACL
	\item filter
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubdescs}{Link Relations}
	\item[service] Points to the service document containing the CMIS repository.  The service document MUST contain only one workspace element.\\ Media Type: \texttt{application/atomsvc+xml}
	\item[self] Points to an URI that returns the Atom entry for this item.  Please see Atom for more information.
	\item[edit] Points to an URI that accepts PUT of Atom entry.  Please see AtomPub for more information.
	\item[describedby] Points to the type definition as an Atom entry for the type of this item.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions] Points to the allowable actions document for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/relationships] Points to the relationships feed for this object.
	\item[http://docs.oasis-open.org/ns/cmis/link/200908/acl] Points to the ACL document for this object.
\end{cmisatompubdescs}

\begin{cmisatompubitems}{The following CMIS Atom extension element MUST be included inside the Atom entry}
	\item \texttt{cmisra:object}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{policyentry-response.txt}


\subsubsection{HTTP PUT}

This does a replacement of the Atom entry with the Atom entry document specified.  If readwrite properties are not included, the repository SHOULD NOT modify them. The updated entry SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{updateProperties}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item Atom Entry documents with CMIS extensions\\
		 \texttt{application/atom+xml;type=entry} or \texttt{application/cmisatom+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/atom+xml;type=entry}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This removes the item from the repository.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{Content Stream}
\label{atom:contentstream}

This is the content stream portion of the document object.  

\subsubsection{HTTP GET}

This returns the content stream.  

It is RECOMMENDED that HTTP Range requests are supported on this resource. Please see \hyperref[intro:rfc2616]{[RFC2616]} for more information on HTTP Range requests. It is RECOMMENDED that HTTP compression is also supported.  

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getContentStream}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item streamId
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item MIME type of the resource
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
	\item 206 Partial Content
\end{cmisatompubitems}


\subsubsection{HTTP PUT}

Sets or replaces the content stream or appends a chunk of content to the existing content stream.

If the client wishes to set a new filename, it MAY add a \texttt{Content-Disposition} header, which carries the new filename. The disposition type MUST be "attachment". The repository SHOULD use the "filename" parameter and SHOULD ignore all other parameters. (See \hyperref[intro:rfc2183]{[RFC2183]} and \hyperref[intro:rfc2231]{[RFC2231]}.)


\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{setContentStream}
	\item \cmisservicelink{appendContentStream}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item overwriteFlag\\If not specified, this defaults to TRUE in this binding and behaves consistent with AtomPub.
	\item changeToken
	\item append\\If specified and set to \texttt{true}, \cmisservicelink{appendContentStream} is called. Otherwise \cmisservicelink{setContentStream} is called.
	\item isLastChunk
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK, if the resource is updated
	\item 204 No Content, if the resource is updated
	\item 201 Created, if a new resource is created
\end{cmisatompubitems}

\begin{cmisatompubitems}{Headers returned}
	\item \texttt{Content-Location}
	\item \texttt{Location}
\end{cmisatompubitems}


\subsubsection{HTTP DELETE}

This removes the content stream.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{deleteObject}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 204 No Content
\end{cmisatompubitems}


%%
\subsection{AllowableActions Resource}
\label{atom:allowableactionsresource}

This is an AllowableActions document.


\subsubsection{HTTP GET}

This returns the CMIS AllowableActions for a specified object. 

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getAllowableActions}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/cmisallowableactions+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

\cmisexample{atompub/getAllowableActions}


%%
\subsection{ACL Resource}
\label{atom:aclresource}

This is an ACL document.

\subsubsection{HTTP GET}

This returns the CMIS ACL for a specified object.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{getACL}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item onlyBasicPermissions
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/cmisacl+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}

%\cmisatompubhttp{Example server response}{acl-response.txt}

\cmisexample{atompub/getAcl}


\subsubsection{HTTP PUT}

This applies the CMIS ACL for a specified object. The updated ACL SHOULD be returned.

\begin{cmisatompubitems}{CMIS Services}
	\item \cmisservicelink{applyACL}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Arguments}
	\item ACLPropagation
\end{cmisatompubitems}

\begin{cmisatompubitems}{Accept}
	\item \texttt{application/cmisacl+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Media Type}
	\item \texttt{application/cmisacl+xml}
\end{cmisatompubitems}

\begin{cmisatompubitems}{Success Status Codes}
	\item 200 OK
\end{cmisatompubitems}


