DataONE API - 2.0

Supporting multiple API versions

Document Status:
 
Status Comment
DRAFT (leinfelder) Listing scenarios for v1 and v2 interactions.

Overview

In order to accommodate changes to the the SystemMetadata type, new API methods will be introduced. Many existing v1 methods will have the same signatures but any method that deals with the SystemMetadata type will need to have a v2 version.

Requirements

  • All v1 objects are valid v2 objects, save for namespace.
  • All implementations of v2 must implement v1 methods.
  • TDB: only the minimally-necessary v2 methods will be defined. This would require mixed-calls in when interacting with the API.

Scenarios

MN running v1 of the API (Tier 1)

# MN.v1.create()

# Synch

  • MN.v1.listOjects()
  • CN.v1.create()

# Valid getSystemMetadata() calls

  • CN.v2.getSystemMetadata() –> v2.SystemMetadata
  • CN.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.v1.getSystemMetadata() –> v1.SystemMetadata

MN running v2 of the API (Tier 1)

# MN.v2.create()

# Synch

  • MN.v2.listOjects()
  • CN.v2.create()

# Valid getSystemMetadata() calls

  • CN.v2.getSystemMetadata() –> v2.SystemMetadata
  • MN.v2.getSystemMetadata() –> v2.SystemMetadata
  • CN.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.v1.getSystemMetadata() –> v1.SystemMetadata

MN running v1 of the API (Tier 4)

# MN.v1.create()

# Synch

  • MN.v1.listOjects()
  • CN.[v1|v2].create()

# Valid get() calls

  • CN.v2.getSystemMetadata() –> v2.SystemMetadata
  • CN.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.v1.getSystemMetadata() –> v1.SystemMetadata

# Replication to MN.target1 running v1 API

  • MN.v1.getReplica()
  • MN.target1.v1.getSystemMetadata() –> v1.SystemMetadata

# Replication to MN.target2 running v2 API

  • MN.v1.getReplica()
  • MN.target2.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.target2.v2.getSystemMetadata() –> v2.SystemMetadata

# Updates

  • CN.v1.setAccessPolicy() –> MN.target1.v1.systemMetadataChanged()
  • CN.v1.setAccessPolicy() –> MN.target2.v2.systemMetadataChanged()
  • CN.v2.setAccessPolicy() –> MN.target1.v1.systemMetadataChanged() ALLOWED?
  • CN.v2.setAccessPolicy() –> MN.target2.v2.systemMetadataChanged()
../_images/versions_01.png

Figure 1. Mixed MN API version interactions with replication

MN running v2 of the API (Tier 4)

# MN.v2.create()

# Synch

  • MN.v1.listOjects()
  • CN.[v1|v2].create()

# Valid get() calls

  • CN.v2.getSystemMetadata() –> v2.SystemMetadata
  • CN.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.v1.getSystemMetadata() –> v1.SystemMetadata

# Replication to MN.target running v1 API

  • NOT ALLOWED

# Replication to MN.target running v2 API

  • MN.v1.getReplica()
  • MN.target.v1.getSystemMetadata() –> v1.SystemMetadata
  • MN.target.v2.getSystemMetadata() –> v2.SystemMetadata
../_images/versions_02.png

Figure 2. Mixed MN API version interactions with replication The original MN is running v2 of the API

This material is based upon work supported by the National Science Foundation under Grant Numbers 083094 and 1430508.

Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.