New engine mutation support in GraphQL and REST APIs

[lukashornych]

The Java API now supports multiple new engine mutations for more granural engine state transformation as described in the documentation. Unforunately, the GraphQL and REST system APIs still support only a few original engine mutations.

We need to revise the system APIs to support all of the new engine mutations:

• Create new catalog
• Duplicate existing catalog
• Modify catalog name
• Modify catalog schema
• Make catalog alive
• Restore catalog
• Set mutability
• Set catalog state

and extend the control-engine.md documentation to provide variants for GraphQL and REST APIs.

• [ ] revise GraphQL system API
• [ ] revise REST system API
• [ ] document GraphQL system API
• [ ] document REST system API

[novoj]

We should also consider supporting async variants of the mutations returning Progress object.

[lukashornych]

After discussion we will create the following.

First, new mutations in GraphQL system API replacing the existing ones:

following mutations will synchronously wait for the task to complete:

• createNewCatalog
• activateCatalog
• deactivateCatalog
• deleteCatalogIfExists
• duplicateCatalog
• makeCatalogAlive
• makeCatalogImmutable
• makeCatalogMutable
• renameCatalog
• replaceCatalog

following mutation will return progressId immediately and the task will continue asynchronously on server:

• activateCatalogWithProgress
• deactivateCatalogWithProgress
• deleteCatalogIfExistsWithProgress
• duplicateCatalogWithProgress
• makeCatalogAliveWithProgress
• makeCatalogImmutableWithProgress
• makeCatalogMutableWithProgress
• renameCatalogWithProgress
• replaceCatalogWithProgress

In conjunction, there will be new subscription onEngineMutationProgressChange that will accept the progressId from any mutation with progress, and will send each progress update to client until the task is finished via WebSockets.

In the case of the REST system API, the API will be similar in concept:

following mutations will synchronously wait for the task to complete:

• createNewCatalog -> POST /catalogs
• activateCatalog -> PATCH /catalogs/{catalogName} { "state": "ACTIVE" }
• deactivateCatalog -> PATCH /catalogs/{catalogName} { "state": "INACTIVE" }
• deleteCatalogIfExists -> DELETE /catalogs/{catalogName}
• duplicateCatalog -> POST /catalogs/{catalogName}/actions/duplicate/{newCatalogName}
• makeCatalogAlive -> PATCH /catalogs/{catalogName} { "state": "ALIVE" }
• makeCatalogImmutable -> PATCH /catalogs/{catalogName} { "mutable": false }
• makeCatalogMutable -> PATCH /catalogs/{catalogName} { "mutable": true }
• renameCatalog -> PATCH /catalogs/{catalogName} { "name": "newName" }
• replaceCatalog -> POST /catalogs/{catalogName}/actions/replace/{newCatalogName}

following mutation will return progressId immediately and the task will continue asynchronously on server:

• activateCatalogWithProgress -> PATCH /catalogs-async/{catalogName} { "state": "ACTIVE" }
• deactivateCatalogWithProgress -> PATCH /catalogs-async/{catalogName} { "state": "INACTIVE" }
• deleteCatalogIfExistsWithProgress -> DELETE /catalogs-async/{catalogName}
• duplicateCatalogWithProgress -> POST /catalogs-async/{catalogName}/actions/duplicate/{newCatalogName}
• makeCatalogAliveWithProgress -> PATCH /catalogs-async/{catalogName} { "state": "ALIVE" }
• makeCatalogImmutableWithProgress -> PATCH /catalogs-async/{catalogName} { "mutable": false }
• makeCatalogMutableWithProgress -> PATCH /catalogs-async/{catalogName} { "mutable": true }
• renameCatalogWithProgress -> PATCH /catalogs-async/{catalogName} { "name": "newName" }
• replaceCatalogWithProgress -> POST /catalogs-async/{catalogName}/actions/replace/{newCatalogName}

In conjunction, there will be new WebSocket endpoint /catalogs-async/progress/ that will accept the progressId from any mutation with progress, and will send each progress update to client until the task is finished via WebSockets.