CCSDK-2871 DP: Long-term Java API(s) - DRAFT

API uses (generated) ID's or customer provided names? If names are used should we return IDs at all?

03/11/12 Team meeting notes - Niamh, Toine, Rishi, Aditya, Bruno, Phillipe
Pros:

1. Using IDs would have some performance advantage
2. Using the ID seems natural in some cases
3. Using IDs would allow for 'renaming' where possible

Cons:

1. Using ID would mean client has to get/cache ID's all the time.
2. Supporting both names and ID will lead to 'duplicate' methods in Java API and REST API
3. Using a meaningless ID for Module instead for namespace & revision could lead to issues when debugging (only logs with IDs available)

Other considerations:

1. The Java API follow the REST API. If the rest API is using names then the java API should also use names.
2. Create methods should return the (id of the) objects created. If the module already exists, an exception should be thrown.
3. All ID's generated should be in the response. If we return the ID we also need methods to use the ID. If we update the java API to use ID, we should also update the REST API. 
4. OSS RC does NOT use IDs for models
5. OSS RC Does DB Generated ID for objects (fragments)
6. Need separate decision for
   1. Dataspace
   2. Module Set
   3. Module
   4. Anchor
   5. Fragment  

We should not expose internal DB ID for dataspace, module set, module, anchor or fragment. 

We do not want to expose them for the following reasons:

• Migration
• Database Optimization

We would like to reserve the right to change database ID's. You eliminate the option that will shuffle the ID's.

• ID Persistence 

If you delete something and then re create it, if its a fragment inside a network function, it will not have the same ID.

1. Dataspace - Name will be provided by user
2. Module Set -Name will be provided by user
3. Module - Name will be provided by user
4. Anchor - can have multiple ID's (will be mapped to entities outside of CPS). We will return URI for an anchor. We will use a generic key value pair map. We will do a check to make sure it is unique and return URI for anchor.
5. Fragment  - XPath is the correct unique identifier and will be added automatically

1. Maybe only allow if no associated data exist e.g. all fragments using a module should be deleted before a module can be deleted.
2. If the associated data still exists, an exception could be thrown (from REST API)

• We want to able to delete an anchor 
• We should be able to delete a dataspace - un deploying use case
• We need to be able to delete the module and module sets associated with the dataspace.
• Rest API (or any other possible user interface) will have safety checks before deletion:
  • Dataspace - do not delete if any module(set)s are still associated
  • Module Set - do not deleted if any modules (or possible anchors)  associated 
  • Module - do not delete if any any anchor associated with it
  • Anchor - delete allowed from REST (will delete everything underneath)
  • Fragment - delete allowed from REST (will delete everything underneath)

1. Can add business logic to check on create if it already exists. If it exists (and is the same) we do not create it (silently ignore, this is called 'idempotent'.

For now we are not going to be idempotent but we may consider it in the future.

Need to be document clearly as part of Java API proposal (i.e in this wiki!)