API Requirements

We need to expose APIs for configuring, commanding and monitoring replication agents.

Configuration API

• Should allow CRUD operations for agent configs

Command API

• Should allow to trigger a replication request on a specific agent
• Should allow to explicitly create and export a package
• Should allow to explicitly import a formerly created package
• Commands might be issued to multiple agents at once

Monitoring API

• Should allow inspection to internal queues of replication agents
• Should allow inspection of commands history

API endpoints 

Configuration API

• Create config  - POST /libs/sling/replication/config
• Read config - GET /libs/sling/replication/config/{config identifier}
• Update config - PUT /libs/sling/replication/config/{config identifier}
• Delete config - DELETE /libs/sling/replication/config/{config identifier} or POST with :operation=delete

Command API

• Replicate tree - POST /libs/sling/replication/agent/{agentName}/replicate
• Import package - POST /libs/sling/replication/agent/{agentName}/import
• Export package - POST /libs/sling/replication/agent/{agentName}/export

Monitoring API

• Replicate tree history - GET /libs/sling/replication/agent/{agentName}/replicate/history
• Import package history - GET /libs/sling/replication/agent/{agentName}/import/history
• Export package history - GET /libs/sling/replication/agent/{agentName}/export/history
• Internal queue inspection  - GET /libs/sling/replication/agent/{agentName}/queues/{queueName}

API Implementation 

Custom servlets vs Standard servlets

There are two main to implement the APIs: use custom servlets or use standard servlets. 

• Standard servlets 
  • have the advantage that requests are stored in content and security comes for free
  • have the disadvantage that for commands API an additional call must be made to find out the status of the command
  • config apis fit very well the content profile
• Custom servlets
  • have the advantage of being able to give a status in the response after a command is placed
  • have the disadvantage of having to implement custom security checks inside the servlet.

Conclusion:

• Configuration API should be implemented using SlingPostServlet and a full sync should be implemented between config location and ConfigurationAdmin. 
• Command API can be implemented using SlingPostServlet if we can live with the asyncronous status check. 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.
• 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

Flatten vs granular 

The commands and monitoring APIs can be implemented using either a flat or a granular approach (or both)

• Flatten design
  • It permits sending requests to multiple agents which might be desirable at least for replicate requests
  • It is easier to implement as it requires no hierarchy of resources
• Granular design
  • It is resource oriented
  • 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.

 Conclusion: Granular design is desirable if we can get some agreement on how to represent the dynamic hierarchy.

Sample payloads

Replicate to multiple agents

POST /system/replication/all/replicate
Request
{
"action" :  "add",
"paths" : [ "/content/tree1", "/content/tree2" ],
"agents" : [ "publish1", "publish2" ]
}
Response
{
"statusList" : [ { "agent" : "publish1", "status" : "queued" },
{ "agent" : "publish2", "status" : "error" } ]
"id" : "ds54eaw543rft4"
}

Import to multiple agents

POST /system/replication/all/import
Request
{
"action" :  "import",
"paths" : [ "/content/tree1", "/content/tree2" ],
"agents" : [ "publish1", "publish2" ],
"package": "packagestream"
}
-----------------------------separator
Content-Disposition: form-data; name="packagestream"; filename="vltpackage.zip"
Content-Type: application/octetstream


(binary data)
-----------------------------separator


Response
{
"statusList" : [ { "agent" : "publish1", "status" : "queued" },
{ "agent" : "publish2", "status" : "error" } ],
"id": "dfqw43t3g"
}