MindTouch Community Portal
Logged in: Logged in as: Log in
Register
Search:
Page last modified 14:16, 19 Aug 2010 by arnec
User:dev > Specs (Implemented) > Import/Export
Page Notifications Off
Redirected from Deki/Specs (Implemented)/Import/Export

Import/Export

     

    Goals

    • Provide a standardized import/export format.
    • Prevent lengthy operations on the server side that can timeout. 
    • Enable users to export pages, tags, files, and properties in an extensible format.
    • Make the import/export process server-driven so as to be backwards and forward compatible.

    POST:site/export

    public. Generates the commands and manifest used to perform the export.  The order of elements in the request affects export order, so it is important to export pages before their files.

    Uri Parameters 

    None

    Query Parameters
    Name Type Description
    relto int? Page used for path normalization (default:  home page)
    reltopath string? Page used for path normalization.  Ignored if relto parameter is defined.
    Return CodesEdit section
    Name Value Description
    BadRequest 400 Invalid input parameter or request body
    Forbidden 403 Browse access to the page is required
    NotFound 404 Requested page could not be found
    Ok 200 The request completed successfully
    Message FormatEdit section
    Input:
    <export> 
  <page path="{text}" recursive="{bool}" exclude="none|files,props,tags,talk|all" />
  <page id="{int}" recursive="{bool}" exclude="none|files,props,tags,talk|all" />  
    ...
  <file id="{int}" exclude="none|props|all" />
</export>
    Output:
    <export>
  <requests>
    <request method="GET" href="http://host/@api/deki/pages/{id}/contents?reltopath={path}&format=xhtml" dataid="{text1}" >
      <header name="{text}" value="{text}" />
      ...
    </request>
    <request method="GET"  href="http://host/@api/deki/pages/{id}/tags" dataid="{text2}">
      <header name="{text}" value="{text}" />
      ...
    </request>
    <request method="GET"  href="http://host/@api/deki/pages/{id}/properties/{name}" dataid="{text3}">
      <header name="{text}" value="{text}" />
      ...
    </request>
    <request method="GET"  href="http://host/@api/deki/files/{id}" dataid="{text4}">
      <header name="{text}" value="{text}" />
      ...
    </request>
    <request method="GET"  href="http://host/@api/deki/files/{id}/properties" dataid="{text5}">
      <header name="{text}" value="{text}" />
      ...
    </request>
    ...
    <warning reason="{text}" status="{httpstatus}">
      <page path="{text}" recursive="{bool}" exclude="none|files,props|all" />
    </warning>
    ...
  </requests>
  <manifest version="{version}">
    <page dataid="{text1}">
      <title>{text}</title>
      <path>{page path using // to indicate relativity to base export page}</path>
      <language>{text}</language>
      <contents type="{mimetype}"/>
    </page>
    <tags dataid="{text2}">
      <path>{page path using // to indicate relativity to base export page}</path>    
    </tags>
    <property dataid="{text3}">
      <name>{text}</name>
      <path>{page path using // to indicate relativity to base export page}</path>
      <contents type="{mimetype}"/>
    </property> 
    <file dataid="{text4}">
     <filename>{text}</filename>
     <path>{page path using // to indicate relativity to base export page}</path>
     <description>{text}</description>
     <contents type="{mimetype}" />
    </file>
    <property dataid="{text5}">
     <name>{text}</name>
     <filename>{text}</filename>
     <path>{page path using // to indicate relativity to base export page}</path>
     <contents type="{mimetype}"/></property>...  
  </manifest>
</export>

    GET:pages/{pageid}/contentsEdit section

    public. Retrieve the contents of a page.  The export feature will add support for relto={int} and reltopath={path}.

    Uri Parameters
    Name Type Description
    pageid string either an integer page ID, "home", or "=" followed by a double uri-encoded page title
    Query Parameters
    Name Type Description
    relto int? Page used for path normalization (default: none)
    reltopath string? Page used for path normalization.  Ignored if relto parameter is defined.
    Return CodesEdit section
    Name Value Description
    BadRequest 400 Invalid input parameter or request body
    Forbidden 403 Browse access to the page is required
    NotFound 404 Requested page could not be found
    Ok 200 The request completed successfully
    Message FormatEdit section
    Output:
    <content type="{contenttype}">      
  <head>{text}</text>     
  <body>{text}</body>     
  <body target="{target}">{text}</body>    
   <tail>{text}</tail>     
</content>

    POST:site/importEdit section

    public. Generates the commands used to perform the import.  The order of elements in the manifest affects import order, so it is important to list pages before their files/properties and files before their properties. Also, if a given element is listed multiple times, multiple revisions will be created in order.

    Uri Parameters 

    None

    Query Parameters
    Name Type Description
    relto int? Page used for path normalization (default: none)
    reltopath string? Page used for path normalization.  Ignored if relto parameter is defined.
    Return CodesEdit section
    Name Value Description
    BadRequest 400 Invalid input parameter or request body
    Forbidden 403 Browse access to the page is required
    NotFound 404 Requested page could not be found
    Ok 200 The request completed successfully
    Message FormatEdit section
    Input: 
    <manifest version="{version}">
    <page dataid="{text1}">
      <title>{text}</title>
      <path>{page path using // to indicate relativity to base export page}</path>
      <language>{text}</language>
      <contents type="{mimetype}"/>
    </page>
    <tags dataid="{text2}">
      <path>{page path using // to indicate relativity to base export page}</path>    
    </tags>
    <property dataid="{text3}">
      <name>{text}</name>
      <path>{page path using // to indicate relativity to base export page}</path>
      <contents type="{mimetype}"/>
    </property>
    <file dataid="{text4}">
      <filename>{text}</filename>
      <path>{page path using // to indicate relativity to base export page}</path>
      <description>{text}</description>
      <contents type="{mimetype}" />
    </file>
    <property dataid="{text5}">
      <name>{text}</name>
      <filename>{text}</filename>
      <path>{page path using // to indicate relativity to base export page}</path>
      <contents type="{mimetype}"/>
    </property>
    ...
  </manifest>
    Output:
    <requests>
  <request method="POST" href="http://host/@api/deki/pages/{path}/contents?reltopath={path}&edittime={timestamp}&lang={lang}&title={text}" dataid="{text1}" type="{mimetype}" >
    <header name="{text}" value="{text}" />
      ...
  </request>
  <request method="PUT" href="http://host/@api/deki/pages/{path}/tags" dataid="{text2}" type="{mimetype}" >
    <header name="{text}" value="{text}" />
      ...
  </request>
  <request method="PUT" href="http://host/@api/deki/pages/{path}/properties" dataid="{text3}" type="{mimetype}" >
    <header name="{text}" value="{text}" />
      ...
  </request>
  <request method="PUT" href="http://host/@api/deki/pages/{path}/files/{filename}" dataid="{text4}" type="{mimetype}" >
    <header name="{text}" value="{text}" />
      ...
  </request>
  <request method="PUT" href="http://host/@api/deki/pages/{path}/files/{filename}/properties" dataid="{text5}" type="{mimetype}" >
    <header name="{text}" value="{text}" />
      ...
  </request>
  <request method="POST" href="http://host/@api/deki/pages/{id}/security" type="text/xml">
    <body type="xml">
      {xml body to post}
    </body>
  </request>
  <warning reason="{text}" status="401|404">
    <page dataid="{text6}">
      <title>{text}</title>
      <path>{page path using // to indicate relativity to base export page}</path>
      <language>{text}</language>
      <contents type="{mimetype}"/>
    </page>
  </warning>
  ...
</requests>

    Note: A request block wiht a body block will never include a dataid attribute and expects the body to be used as the import content.

    POST:pages/{pageid}/contentsEdit section

    public. Update contents of a page.   The import feature will add support for relto={int}, reltopath={path}, and request mime type of text/xml.

    Uri Parameters

     

    Name Type Description
    pageid string either an integer page ID, "home", or "=" followed by a double uri-encoded page title

     

    Query Parameters
    Name Type Description
    relto int? Page used for path normalization (default: none)
    reltopath string? Page used for path normalization.  Ignored if relto parameter is defined.

     

    Return CodesEdit section
    Name Value Description
    BadRequest 400 Invalid input parameter or request body
    Forbidden 403 Browse access to the page is required
    NotFound 404 Requested page could not be found
    Ok 200 The request completed successfully
    Message FormatEdit section
    Input:
    <content type="{contenttype}">      
  <head>{text}</text>     
  <body>{text}</body>     
  <body target="{target}">{text}</body>    
   <tail>{text}</tail>     
</content>

    Q & A

    Q. What to do if an error occurs during part of the export, such as a page not found?

    A.  The requests collection will contain a warning element for each failed item, which contains error details and the element that produced the error.  The import/export client can then display this information and allow the user to decide whether to proceed with the import/export.

     

    Q. How to handle paths relative to a specified import/export root?

    A.  Whenever content is imported/exported, it is always relative to a given page.  The api allows the caller to specify the root page using the relto parameter.   All pages, files, internal links, and internal images will be made relative to this path:

    • Normalized page paths will be relative to the root page, which is indicated by //.  Paths outside the root page will remain absolute.
    • Internal links will be returned as <a href.path="//MindTouch_Deki/FAQ/Extensions" href.achor="{text}" href.query="{text}" />
    • File links will be returned as:  <img src.path="//MindTouch_Deki/FAQ/Extensions" src.filename="Crystal_Clear_app_ksysguard.png"  /> .  The page path and filename are separated to avoid encoding issues.

     

    Q. What to do with redirect pages?

    If the user requests to export a page that has a redirect child page, the redirect child page will automatically be excluded from the export.  If the user specifically requests to export a redirect page, a warning will be returned. 

    Tag page
    What links here

    Files 0

    Attach file or image
     
    You must login to post a comment.
    MindTouch Social Knowledge Base

    Copyright © 2011 MindTouch, Inc. Powered by