incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Marius Petria (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Sling > Replication - HTTP API (proposal)
Date Thu, 13 Feb 2014 14:03:00 GMT
<html>
    <head>
        <meta name="viewport" content="width=device-width" />
        <base href="https://cwiki.apache.org/confluence" />
        <style type="text/css">
    body, #email-content, #email-content-inner { font-family: Arial,FreeSans,Helvetica,sans-serif;
}
    body, p, blockquote, pre, code, td, th, li, dt, dd { font-size: 13px; }
    small { font-size: 11px; }

    body { width:100% !important; -webkit-font-smoothing: antialiased; }

    body,
    #email-wrapper { background-color: #f0f0f0; }
    #email-wrapper-inner { padding: 20px; text-align: center; }
    #email-content-inner { background-color: #fff; border: 1px solid #bbb; color: $menuTxtColour;
padding:20px; text-align:left; }
    #email-wrapper-inner > table { width: 100%; }
    #email-wrapper-inner.thin > table { margin: 0 auto; width: 50%; }
    #email-footer { padding: 0 16px 32px 16px; margin: 0; }

    .email-indent { margin: 8px 0 16px 0; }
    .email-comment { margin: 0 0 0 56px; }
    .email-comment.removed { background-color: #ffe7e7; border: 1px solid #df9898; padding:
0 8px;}

    #email-title-avatar { text-align: left; vertical-align: top; width: 48px; padding-right:
8px; }
    #email-title-flavor { margin: 0; padding: 0 0 4px 0; }
    #email-title-heading { font-size: 16px; line-height: 20px; min-height: 20px; margin: 0;
padding: 0; }
    #email-title .icon { border: 0; padding: 0 5px 0 0; text-align: left; vertical-align:
middle; }

    #email-actions { border-top: 1px solid #bbb; color: #505050; margin: 8px 0 0 0; padding:
0; }
    #email-actions td { padding-top: 8px; }
    #email-actions .left { max-width: 45%; text-align: left; }
    #email-actions .right { text-align: right; }
    .email-reply-divider { border-top: 1px solid #bbb; color: #505050; margin: 32px 0 8px
0; padding: 8px 0; }
    .email-section-title { border-bottom: 1px solid #bbb; margin: 8px 0; padding: 8px 0 0
0; }

    .email-metadata { color: #505050; }

    a { color: #326ca6; text-decoration: none; }
    a:hover { color: #336ca6; text-decoration: underline; }
    a:active {color: #326ca6; }

    a.email-footer-link { color: #505050; font-size: 11px; }

    .email-item-list { list-style: none; margin: 4px 0; padding-left: 0; }
    .email-item-list li { list-style: none; margin: 0; padding: 4px 0; }
    .email-list-divider { color: #505050; padding: 0 0.35em; }
    .email-operation-icon { padding-right: 5px; }

    .avatar { -ms-interpolation-mode: bicubic; border-radius: 3px;}
    .avatar-link { margin: 2px; }

    .tableview th { border-bottom: 1px solid #69C; font-weight: bold; text-align: left; }
    .tableview td { border-bottom: 1px solid #bbbbbb; text-align: left; padding: 4px 16px
4px 0; }

    .aui-message {  margin: 1em 0; padding: 8px; }
    .aui-message.info { background-color: #e0f0ff; border: 1px solid #9eb6d4; }
    .aui-message.success { background-color: #ddfade; border: 1px solid #93c49f; }
    .aui-message.error,
    .aui-message.removed { background-color: #ffe7e7; border: 1px solid #df9898; color: #000;
}

    .call-to-action-table { margin: 10px 1px 1px 1px;}
    .call-to-cancel-container, .call-to-action-container { padding: 5px 20px; }
    .call-to-cancel-container { border: 1px solid #aaa; background-color: #eee; border-radius:
3px; }
    .call-to-cancel-container a.call-to-cancel-button { background-color: #eee; font-size:
14px; line-height: 1; padding: 0; margin: 0; color: #666; font-family: sans-serif;}
    .call-to-action-container { border: 1px solid #486582;  background-color: #3068A2; border-radius:
3px; padding: 4px 10px; }
    .call-to-action-container a.call-to-action-button { background-color: #3068A2; font-size:
14px; line-height: 1; padding: 0; margin: 0; color: #fff; font-weight: bold; font-family:
sans-serif; }

    /** The span around the inline task checkbox image */
    .diff-inline-task-overlay {
        display: inline-block;
        text-align: center;
        height: 1.5em;
        padding: 5px 0px 1px 5px;
        margin-right: 5px;
        /** Unfortunately, the negative margin-left is stripped out in gmail */
        margin-left: -5px;
    }

            @media handheld, only screen and (max-device-width: 480px) {
        div, a, p, td, th, li, dt, dd { -webkit-text-size-adjust: auto; }
        small, small a { -webkit-text-size-adjust: 90%; }

        td[id=email-wrapper-inner] { padding: 2px !important; }
        td[id=email-content-inner] { padding: 8px !important; }
        td[id="email-wrapper-inner"][class="thin"] > table { text-align: left !important;
width: 100% !important; }
        td[id=email-footer] { padding: 8px 12px !important; }
        div[class=email-indent] { margin: 8px 0px !important; }
        div[class=email-comment] { margin: 0 !important; }

        p[id=email-title-flavor] a { display: block; } /* puts the username and the action
on separate lines */
        p[id=email-permalink] { padding: 4px 0 0 0 !important; }

        table[id=email-actions] td { padding-top: 0 !important; }
        table[id=email-actions] td.right { text-align: right !important; }
        table[id=email-actions] .email-list-item { display: block; margin: 1em 0 !important;
word-wrap: normal !important; }
        span[class=email-list-divider] { display: none; }
    }



        </style>
    </head>
    <body style="font-family: Arial, FreeSans, Helvetica, sans-serif; font-size: 13px;
width: 100%; -webkit-font-smoothing: antialiased; background-color: #f0f0f0">
        <table id="email-wrapper" width="100%" cellspacing="0" cellpadding="0" border="0"
style="background-color: #f0f0f0">
            <tbody>
                <tr valign="middle">
                    <td id="email-wrapper-inner" style="font-size: 13px; padding: 20px;
text-align: center">
                        <table id="email-content" cellspacing="0" cellpadding="0" border="0"
style="font-family: Arial, FreeSans, Helvetica, sans-serif; width: 100%">
                            <tbody>
                                <tr valign="top">
                                    <td id="email-content-inner" align="left" style="font-family:
Arial, FreeSans, Helvetica, sans-serif; font-size: 13px; background-color: #fff; border: 1px
solid #bbb; padding: 20px; text-align: left">
                                        <table id="email-title" cellpadding="0" cellspacing="0"
border="0" width="100%">
                                            <tbody>
                                                <tr>
                                                    <td id="email-title-avatar" rowspan="2"
style="font-size: 13px; text-align: left; vertical-align: top; width: 48px; padding-right:
8px"> <img class="avatar" src="cid:avatar_4c041938617b8c72cbf4bea1130b56fa" border="0"
height="48" width="48" style="-ms-interpolation-mode: bicubic; border-radius: 3px" /> </td>
                                                    <td valign="top" style="font-size:
13px">
                                                        <div id="email-title-flavor" class="email-metadata"
style="margin: 0; padding: 0 0 4px 0; color: #505050">
                                                            <a href="    https://cwiki.apache.org/confluence/display/~mpetria
" style="color:#326ca6;text-decoration:none;; color: #326ca6; text-decoration: none">Marius
Petria</a> created a page:
                                                        </div> </td>
                                                </tr>
                                                <tr>
                                                    <td valign="top" style="font-size:
13px"> <h2 id="email-title-heading" style="font-size: 16px; line-height: 20px; min-height:
20px; margin: 0; padding: 0"> <a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=38572805"
style="color: #326ca6; text-decoration: none"> <img class="icon" src="cid:page-icon"
alt="" style="border: 0; padding: 0 5px 0 0; text-align: left; vertical-align: middle" />
<strong style="font-size:16px;line-height:20px;vertical-align:top;">Replication - HTTP
API (proposal)</strong> </a> </h2> </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                        <div class="email-indent" style="margin: 8px 0
16px 0">
                                            <div class="email-page">
                                                <h1 id="Replication-HTTPAPI(proposal)-APIRequirements">API
Requirements</h1>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">We need to
expose APIs for configuring, commanding and monitoring replication agents.</p>
                                                <h2 id="Replication-HTTPAPI(proposal)-ConfigurationAPI">Configuration
API</h2>
                                                <ul style="margin-left: 0.375in;">
                                                    <li style="font-size: 13px"> <span>Should
allow CRUD operations for agent configs</span> </li>
                                                    <li style="font-size: 13px"> <span>Configs
need to have a JCR representation (either the default one or a new one) in order to support
the following workflow: configure all agents on a author instance and replicate configuration
to all publish instances.</span> </li>
                                                </ul>
                                                <h1 id="Replication-HTTPAPI(proposal)-CommandAPI">Command
API</h1>
                                                <ul style="margin-left: 0.375in;">
                                                    <li style="font-size: 13px"> <span>Should
allow Replicate/Import Package/Export Package</span> </li>
                                                    <li style="font-size: 13px"> <span>Commands
might be issued to multiple agents at once (but this not a strong requirement I think)</span>
</li>
                                                </ul>
                                                <h2 id="Replication-HTTPAPI(proposal)-MonitoringAPI">Monitoring
API</h2>
                                                <ul style="margin-left: 0.375in;">
                                                    <li style="font-size: 13px"> <span>Should
allow inspection to internal queues of replication agents</span> </li>
                                                    <li style="font-size: 13px"> <span>Should
allow inspection of commands history</span> </li>
                                                </ul>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <h1 id="Replication-HTTPAPI(proposal)-APIendpoints">API
endpoints&nbsp;</h1>
                                                <h2 id="Replication-HTTPAPI(proposal)-ConfigurationAPI.1">Configuration
API</h2>
                                                <ul>
                                                    <li style="font-size: 13px">Create
config&nbsp; - POST /system/replication/config</li>
                                                    <li style="font-size: 13px">Read
config - GET /system/replication/config/publish</li>
                                                    <li style="font-size: 13px">Update
config - PUT /system/replication/config/publish</li>
                                                    <li style="font-size: 13px">Delete
config - DELETE /system/replication/config/publish</li>
                                                </ul>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <h2 id="Replication-HTTPAPI(proposal)-CommandAPI.1">Command
API</h2>
                                                <p style="font-size: 13px">For command
and monitoring APIs we can have two kind of APIs. We do not need to implement both variants,
and I do not think there is a strict requirement for choosing one variant or another.</p>
                                                <p style="font-size: 13px">The flattened
APIs can take as parameters multiple agents and the granular APIs can take as parameters just
on</p>
                                                <h3 id="Replication-HTTPAPI(proposal)-CommandsAPI-flattened">Commands
API - flattened</h3>
                                                <p style="font-size: 13px">Replicate
tree - POST /system/replication/all/replicate</p>
                                                <p style="font-size: 13px">Import package
- POST /system/replication/all/import</p>
                                                <p style="font-size: 13px">Export package
- POST /system/replication/all/export</p>
                                                <h3 id="Replication-HTTPAPI(proposal)-CommandsAPI-granular">Commands
API - granular</h3>
                                                <p style="font-size: 13px">Replicate
tree - POST /system/replication/agent/{agentName}/replicate</p>
                                                <p style="font-size: 13px">Import package
- POST /system/replication/agent/{agentName}/import</p>
                                                <p style="font-size: 13px">Export package
- POST /system/replication/agent/{agentName}/export</p>
                                                <h2 id="Replication-HTTPAPI(proposal)-MonitoringAPI.1">Monitoring
API</h2>
                                                <h3 id="Replication-HTTPAPI(proposal)-MonitoringAPIs-flattened">Monitoring
APIs - flattened</h3>
                                                <p style="font-size: 13px">Replicate
tree - GET /system/replication/all/replicate/history?agent={agentName}</p>
                                                <p style="font-size: 13px">Import package
- GET /system/replication/all/import/history?agent={agentName}</p>
                                                <p style="font-size: 13px">Export package
- GET /system/replication/all/export/history?agent={agentName}</p>
                                                <p style="font-size: 13px">Internal
queues&nbsp; - GET /system/replication/all/queues?agent={agentName}&amp;queue={queueName}</p>
                                                <ul style="margin-left: 0.375in;">
                                                    <li style="font-size: 13px"> <span>Lists
information about the packages in a queue</span> </li>
                                                </ul>
                                                <h3 id="Replication-HTTPAPI(proposal)-MonitoringAPIs-granular">Monitoring
APIs - granular</h3>
                                                <p style="font-size: 13px">Replicate
tree - GET /system/replication/agent/{agentName}/replicate/history</p>
                                                <p style="font-size: 13px">Import package
- GET /system/replication/agent/{agentName}/import/history</p>
                                                <p style="font-size: 13px">Export package
- GET /system/replication/agent/{agentName}/export/history</p>
                                                <p style="font-size: 13px">Internal
queues&nbsp; - GET /system/replication/agent/{agentName}/queues/{queueName}</p>
                                                <ul style="margin-left: 0.375in;">
                                                    <li style="font-size: 13px"> <span>Lists
information about the packages in a queue</span> </li>
                                                </ul>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <h1 id="Replication-HTTPAPI(proposal)-APIImplementation">API
Implementation&nbsp;</h1>
                                                <h2 id="Replication-HTTPAPI(proposal)-CustomservletsvsStandardservlets">Custom
servlets vs Standard servlets</h2>
                                                <p style="font-size: 13px">There are
two main to implement the APIs: use custom servlets or use standard servlets.&nbsp;</p>
                                                <ul>
                                                    <li style="font-size: 13px">Standard
servlets&nbsp;
                                                        <ul>
                                                            <li style="font-size: 13px">have
the advantage that requests are stored in content and security comes for free</li>
                                                            <li style="font-size: 13px">have
the disadvantage that for commands API an additional call must be made to find out the status
of the command</li>
                                                            <li style="font-size: 13px">config
apis fit very well the content profile</li>
                                                        </ul> </li>
                                                    <li style="font-size: 13px">Custom
servlets
                                                        <ul>
                                                            <li style="font-size: 13px">have
the advantage of being able to give a status in the response after a command is placed</li>
                                                            <li style="font-size: 13px">have
the disadvantage of having to implement custom security checks inside the servlet.</li>
                                                        </ul> </li>
                                                </ul>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">Conclusion:</p>
                                                <ul>
                                                    <li style="font-size: 13px">Configuration
API should be implemented using SlingPostServlet.&nbsp;</li>
                                                    <li style="font-size: 13px">Command
API can be implemented using SlingPostServlet if we can live with the asyncronous status check.&nbsp;It
is important to have in mind that the replication commands are asynchronous by default as
there might be some queues that are used the different parts of a replication request. Hence
finding out if a replication request was completely finished will require inspecting the history
most of the times.</li>
                                                    <li style="font-size: 13px">Monitoring
API should be implemented with custom servlets at least for internal queues as they display
live info which would be tedious to sync in the repo</li>
                                                </ul>
                                                <h2 id="Replication-HTTPAPI(proposal)-Flattenvsgranular">Flatten
vs granular&nbsp;</h2>
                                                <p style="font-size: 13px">The commands
and monitoring APIs can be implemented using either a flat or a granular approach (or both)</p>
                                                <ul>
                                                    <li style="font-size: 13px">Flatten
design
                                                        <ul>
                                                            <li style="font-size: 13px">It
permits sending requests to multiple agents which might be desirable at least for replicate
requests</li>
                                                            <li style="font-size: 13px">It
is easier to implement as it requires no hierarchy of resources</li>
                                                        </ul> </li>
                                                    <li style="font-size: 13px">Granular
design
                                                        <ul>
                                                            <li style="font-size: 13px">It
is resource oriented</li>
                                                            <li style="font-size: 13px">One
needs to implement either a ResourceProvider or a JCR syncronization for agents and queues
in order to represent the hierarchy. There is no consensus on which is best.</li>
                                                        </ul> </li>
                                                </ul>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">&nbsp;Conclusion:
Granular design is desirable if we can get some agreement on how to represent the dynamic
hierarchy.</p>
                                                <p style="font-size: 13px"> <span
style="line-height: 1.4285715;"> <br /> </span> </p>
                                                <h1 id="Replication-HTTPAPI(proposal)-Samplepayloads">
<span style="line-height: 1.4285715;">Sample payloads</span> </h1>
                                                <h3 id="Replication-HTTPAPI(proposal)-Replicatetomultipleagents">
<span style="line-height: 1.4285715;">Replicate to multiple agents</span> </h3>
                                                <p style="font-size: 13px"> <code
style="line-height: 1.4285715;; font-size: 13px">code</code><span style="line-height:
1.4285715;">&nbsp;</span> </p>
                                                <p style="font-size: 13px"> <span
style="line-height: 1.4285715;">POST /system/replication/all/replicate</span> </p>
                                                <p style="font-size: 13px">Request</p>
                                                <p style="font-size: 13px">{</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;action&quot; :&nbsp; &quot;add&quot;,</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;paths&quot; : [ &quot;/content/tree1&quot;, &quot;/content/tree2&quot;
],</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;agents&quot; : [ &quot;publish1&quot;, &quot;publish2&quot;
]</p>
                                                <p style="font-size: 13px">}</p>
                                                <p style="font-size: 13px">Response</p>
                                                <p style="font-size: 13px">{</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;statusList&quot; : [ { &quot;agent&quot; : &quot;publish1&quot;,
&quot;status&quot; : &quot;queued&quot; },</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">{ &quot;agent&quot; : &quot;publish2&quot;, &quot;status&quot;
: &quot;error&quot; } ]</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;id&quot; : &quot;ds54eaw543rft4&quot;</p>
                                                <p style="font-size: 13px">}</p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px"> <code
style="font-size: 13px">code</code> </p>
                                                <h3 id="Replication-HTTPAPI(proposal)-Importtomultipleagents">Import
to multiple agents</h3>
                                                <p style="font-size: 13px"> <code
style="font-size: 13px">code</code> </p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">POST /system/replication/all/import</p>
                                                <p style="font-size: 13px">Request</p>
                                                <p style="font-size: 13px">{</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;action&quot; :&nbsp; &quot;import&quot;,</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;paths&quot; : [ &quot;/content/tree1&quot;, &quot;/content/tree2&quot;
],</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;agents&quot; : [ &quot;publish1&quot;, &quot;publish2&quot;
],</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;package&quot;: &quot;packagestream&quot;</p>
                                                <p style="font-size: 13px">}</p>
                                                <p style="font-size: 13px">-----------------------------separator</p>
                                                <p style="font-size: 13px">Content-Disposition:
form-data; name=&quot;packagestream&quot;; filename=&quot;vltpackage.zip&quot;</p>
                                                <p style="font-size: 13px">Content-Type:
application/octetstream</p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">(binary data)</p>
                                                <p style="font-size: 13px">-----------------------------separator</p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px">Response</p>
                                                <p style="font-size: 13px">{</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;statusList&quot; : [ { &quot;agent&quot; : &quot;publish1&quot;,
&quot;status&quot; : &quot;queued&quot; },</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">{ &quot;agent&quot; : &quot;publish2&quot;, &quot;status&quot;
: &quot;error&quot; } ],</p>
                                                <p style="margin-left: 0.375in;; font-size:
13px">&quot;id&quot;: &quot;dfqw43t3g&quot;</p>
                                                <p style="font-size: 13px">}</p>
                                                <p style="font-size: 13px">&nbsp;</p>
                                                <p style="font-size: 13px"> <code
style="font-size: 13px">code</code> </p>
                                            </div>
                                        </div>
                                        <table id="email-actions" class="email-metadata"
cellspacing="0" cellpadding="0" border="0" width="100%" style="border-top: 1px solid #bbb;
color: #505050; margin: 8px 0 0 0; padding: 0; color: #505050">
                                            <tbody>
                                                <tr>
                                                    <td class="left" valign="top" style="font-size:
13px; padding-top: 8px; max-width: 45%; text-align: left"> <span class="email-list-item"><a
href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=38572805" style="color:
#326ca6; text-decoration: none">View Online</a> </span> <span class="email-list-divider"
style="color: #505050; padding: 0 0.350em">&middot;</span> <span class="email-list-item"><a
href="https://cwiki.apache.org/confluence/plugins/likes/like.action?contentId=38572805" style="color:
#326ca6; text-decoration: none">Like</a> </span> <span class="email-list-divider"
style="color: #505050; padding: 0 0.350em">&middot;</span> <span class="email-list-item"><a
href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=38572805&amp;showComments=true&amp;showCommentArea=true#addcomment"
style="color: #326ca6; text-decoration: none">Add Comment</a> </span> </td>
                                                    <td class="right" width="50%" valign="top"
style="font-size: 13px; padding-top: 8px; text-align: right"> <span class="email-list-item"><a
href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=SLING"
style="color: #326ca6; text-decoration: none">Stop watching space</a> </span>
<span class="email-list-divider" style="color: #505050; padding: 0 0.350em">&middot;</span>
<span class="email-list-item"><a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action"
style="color: #326ca6; text-decoration: none">Manage Notifications</a> </span>
</td>
                                                </tr>
                                            </tbody>
                                        </table> </td>
                                </tr>
                            </tbody>
                        </table> </td>
                </tr>
                <tr>
                    <td id="email-footer" align="center" style="font-size: 13px; padding:
0 16px 32px 16px; margin: 0"> <small style="font-size: 11px"> This message was sent
by <a class="email-footer-link" style="color:#505050;font-size:11px;text-decoration:none;;
color: #326ca6; text-decoration: none; color: #505050; font-size: 11px" href="http://www.atlassian.com/software/confluence">Atlassian
Confluence</a> 5.0.3, <a class="email-footer-link" style="color:#505050;font-size:11px;text-decoration:none;;
color: #326ca6; text-decoration: none; color: #505050; font-size: 11px" href="http://www.atlassian.com/software/confluence/overview/team-collaboration-software?utm_source=email-footer">Team
Collaboration Software</a> </small> </td>
                </tr>
            </tbody>
        </table>
    </body>
</html>
Mime
View raw message