Spec Status
This spec was deemed redundant with the import/export feature - this spec has been abandoned but is kept here for historical reasons.
Introduction
Page Copying will provide API level functionality for creating a copying specific revisions of pages and files. Properties and tags can already be migrated with existing API functionality.
Purpose
Used as the underlying mechanism for page drafts.
Use Cases
Use cases only describe the involvement of copying, not other parts of the process that may also need to occur.
Create new draft
- Copy head revision of source page to draft location
- Copy all file head revisions to draft location
Publish draft
- Iterate through all page revisions not marked as hidden and copy them back
- Iterate through all file revisions not marked as hidden and copy them back
Functional Specification
Goals
- Page/File & revision level copying (assumes head, if not specified)
- Copies only specified revision
- Attaches property to copied resource with source id and revision
Non-goals
- Not meant to have knowledge of the purpose of the copy
- Does not make assumptions about source or destination locations
- Does not perform any merging at destination, only replacement by creating a new revision
Technical Specification
Mapping Local File references
When pages and files are copied, the page document may need to be updated to reference local instances of the files. This mapping may occur on either a page or a file copy depending on the whether or not the resource being copied already exists. There are only two scenarios under which the mapping needs to be considered:
File being copied does not yet exist at destination
- File copy determines that copy is creating a new file (i.e. a new fileid) at destination
- File being copied inspects the destination parent document and replaces any Uri's referencing the origin fileid path with the new fileid path
Files being copied to a location where that filename already exist do not require rewrites since the parent document is already referencing the local file and will automatically pick up the new file revision
Page is copied to an existing destination
- Page copy determines that the destination location already exists (i.e. copy is a new revision on an existing pageid)
- Page being copied checks filenames attached to origin to determine if those files exist at the destination
- For all filename matches, page replaces any Uri's referencing the origin fileid path with the destination fileid path
Pages being copied to a new location do not require a rewrite since there are no local files yet and the references to the original files still work (which is also useful for a modified version of the draft system that does not copy files.
Open Questions
- Does the file copy that causes a page rewrite do so as a new revision of the page or update the page silently in place?
- Or does it create a new revision but immediately hide the previous revision?
API requirements
New Feature: Copy Page
Signature: POST:pages/{pageid}/copy
Access: Public
Query Parameters
| Name | Type | Defaut | Description |
| to | string | none | Destination title |
| revision | int? | head revision | Revision to copy |
Response
| Response | Response Body | Description |
| Created (201) | application/xml | the page was copied, and a Location header provides the uri of the copy |
| Bad Request (400) | text/html | request could not be completed, because of invalid data in the request |
New Feature: Copy File
Signature: POST:files/{fileid}/copy
Access: Public
Query Parameters
| Name | Type | Defaut | Description |
| to | int | none | Destination page id |
| revision | int? | head revision | Revision to copy |
Response
| Response | Response Body | Description |
| Created (201) | application/xml | the file was copied, and a Location header provides the uri of the copy |
| Bad Request (400) | text/html | request could not be completed, because of invalid data in the request |
