Unclear behaviour when implementing /systems/{systemId}/deployments

[SpeckiJ]

When implementing the Endpoint /systems/{systemId}/deployments I came across some difficulties

Situation

The System when posted is standalone and does not have any relation with a specific Deployment. The Deployment when posted has its systems linked as a DeployedSystem (schema):

"deployedSystems": [
  {
      "name": "water_temp_sensor",
      "system": 
      {
          "href": "https://data.example.org/api/systems/36584?f=sml",
      }  
  },
  {
  
      "name": "wind_sensor",
      "system": 
          {
              "href": "https://data.example.org/api/systems/47752?f=sml",
          }
      }
]

The history of this structure is also discussed in #30 .

Problem

Implementing the endpoint /systems/{systemId}/deployments requires that I have somehow linked the deployment with the system in my datastore - else i cannot retrieve the deployment using the ID of a system.

I do not quite understand how I am supposed to create that link - the generic structure deployedSystems does not give any information about whether the systems are stored in the same API (or in an external/federated API), additionally there only is an arbitrarily complex URL and no direct ID of a system (optionally there is a uid but this is not required and is not the systemId that is referenced in the url when requesting deployments).

Workaround

Currently this therefore requires the workflow:

1. Parse the URL to first check whether it is a local URL to myself (very difficult in architectures with loadbalancers/reverse-proxies etc.)
2. Try to extract the ID from the URL
3. If ID is present, link it internally to the system

Which produces a lot of undefined behaviour - e.g. what happens if there is no system with the specified ID locally, but the deployment references it? Do i just accept a POST which knowingly has bad links?

Additionally there should probably be a note somewhere that the /systems/{systemId}/deployments may not be the absolute truth, as other Deployments may be stored on different servers.

[alexrobin]

Discussed during 09/05 Telecon:

Document that href can be either:

• a URL pointing to an external system resource
• a URN that points to a local system resource.