API Requirements

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

...

• Should allow CRUD operations for agent configs
• 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.

Command API

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 packageShould allow Replicate/Import Package/Export Package
• Commands might be issued to multiple agents at once (but this not a strong requirement I think)

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/systemsling/replication/config
• Read config - GET /libs/systemsling/replication/config/publish{config identifier}
• Update config - PUT /libs/systemsling/replication/config/publish{config identifier}
• Delete config - DELETE /libs/systemsling/replication/config/publish

...

• {config identifier} or POST with :operation=delete

Command API

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.

The flattened APIs can take as parameters multiple agents and the granular APIs can take as parameters just on

Commands API - flattened

• Replicate tree - POST /

...

• libs/

...

Import package - POST /system/replication/all/import

Export package - POST /system/replication/all/export

Commands API - granular

...

• 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

Monitoring APIs - flattened

• Replicate tree

...

• history

...

• - GET /

...

• libs/

...

Export package - GET /system/replication/all/export/history?agent={agentName}

Internal queues  - GET /system/replication/all/queues?agent={agentName}&queue={queueName}

• Lists information about the packages in a queue

Monitoring APIs - granular

...

• 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}

• Lists information about the packages in a queue

API Implementation 

Custom servlets vs Standard servlets

...

• 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

...