Cloning Resources

The are lots of ways to walk the API: the todo app displays it with a user interface; the general api browser walks and allows simple updates. Cloning resources extends the general purpose client and programmatically makes it possible to deal with complicated updates—its purpose is to make copies in bulk without people intervention. One easy example is the business problem of moving data between environments (eg between test to another test environment, or bringing production data back into another environment or from a production staging/testing into production).

All of this is made possible because hypermedia uses forms to instruct the client.

Getting started: Admin

Simple general principles

• have a client version that is the desired version
• match this against server version
• resolve differences and submit appropriate actions

Two operations

1. Clone a resource: your client version has a different root parent (ie it has an identity that does not yet exists). The change is significant that the resources below to root need to be re-parented (or put differently a part of the tree is copied and grafted into a new parent). This solution would require POST throughout but also match new resource against the old ones (ie substitutions).
2. Update existing resource: your client version is a copy of the server and all resource identities are the same; the only change is to remove some items and change a couple of attributes. This solution would do a mixture of DELETE and PUT requests.

All of this done using the semantic network library and the purpose of this tutorial is show how it is used (not how to build it) and the mental model it requires.

Note: the drag’n’drop is just user-sugar to make the interaction practical. Again, if you want to understand the mechanics drag’n’drop look at the code (but the issue is that HTML5 API here is the right thing to do).

Both processes require first a copy to made.

Have a copy

The semantic-network library provides get (as well as create, update and delete) to help build up a cache of network of data based on link relations. Study the implementation below to see that primarily all the developer needs to know is the link relation and can optionally add strategies for eager and lazy loading, for instance. In this implementation, the knowledge of the link relations is kept out of the framework specific code (hence in the domain folder) for the usual reasons of reuse, testing and intention. Also, note that types are explicitly defined and are used in parameters and return types.

Create new

The semantic-network library provides sync to walk the network of data based on link relations loading up representations and their forms and then working out whether to update, create or delete based on the presented representation/document. Study the implementation below to see that:

• on each link relation (eg rel: /todos/) the strategies provides a recursive structure for depth and width control.
• short form parameter spread (...syncResult) that passes through necessary parameters
• long form parameter destructuring ({resource, document, options}) where you want to include options
• using a resolver for forward references and references to collections that are naturally parented outside the current tree (ie tags are parented across tenants)
• changing batch size (ie concurrent versus serial operations).

Create or Update?

What is the difference between the two in the context of hypermedia? How to know whether to call create or update? You don’t. The question the code asks of the data is the difference in state. Do you exist? Are you different?

In the sample, you can force a create by changing the root resource identity. This requires two changes, remove the ‘self’ link and change the ‘name’ attribute.

Update existing

1. Drag the organisation off onto the desktop (that will get a copy as JSON, aka hydrate)
2. Update the JSON
3. Drag back onto the same organisation