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" }
1 Comment
Carsten Ziegeler
For the monitoring API we should go with the granular one, as the request is directly addressing the agent (resource)
The command API should directly address the agent and provide the information via request parameters or http headers etc., e.g.
POST /system/replication/agent/{agentName}