7.8 Manage resources in L2

Resources can be registered and removed from the local registry in a similar way as it is done in the Core for L1. Even if the endpoint is different and the resource will be saved in the local registry, the resource metadata is the same as it is for L1. Please see chapter 2.8 for concrete examples of the expected payload. The only difference is that we do not specify filtering and access policies. In L2, the federation access policy is always used, which grants access to resources only if a token issued by a federation member is presented.

2.5.1 Resource Metadata registration

To register a resource, send a POST request to the /local/resources path (e.g http://127.0.0.1:8080/local/resources)) with a payload that includes a list of resources metadata.

[{
  "internalId": "isen1",
  "pluginId": "platform_01",
  "resource": {
    "@c": ".StationarySensor",
    "name": "DefaultSensor1",
    "description": [
      "Default sensor for testing RAP"
    ],
    "featureOfInterest": {
      "name": "temperature feature of interest",
      "description": [
        "measures temperature"
      ],
      "hasProperty": [
        "temperature",
        "humidity",
        "atmosphericPressure",
        "carbonMonoxideConcentration",
        "nitrogenDioxideConcentration"
      ]
    },
    "observesProperty": [
      "temperature",
      "humidity",
      "atmosphericPressure",
      "carbonMonoxideConcentration",
      "nitrogenDioxideConcentration"
    ],
    "locatedAt": {
      "@c": ".WGS84Location",
      "longitude": 52.513681,
      "latitude": 13.363782,
      "altitude": 15,
      "name": "Berlin",
      "description": [
        "Grosser Tiergarten"
      ]
    },
    "interworkingServiceURL": "https://symbiotedoc.tel.fer.hr/"
  }
}]

As you can see, the registration message is the same as in L1, with the only difference that we do not specify filtering and access policies. In L2, the federation access policy is always used, which grants access to resources only if a token issued by a federation member is presented. The result will be a list of the successfully registered resources. Please note that, contrary to L1 registration in which a SymbIoTe Id was generated upon registration, in this case this Id is not generated at all at this stage. It just means that the local registry is aware of this resource. Also, resources can be registered at L1 and 2 at the same time, so if the resource was already registered for L1, it will be updated locally with the provided metadata.

Only JSON format is allowed for local registration. The use of RDF format is not supported at L2.

2.5.2 Resource Metadata unregistration

Same as with registering, a list of resources can be deleted from the local registry in a similar way of L1 by sending a DELETE request to /local /resources and providing a comma-separated list of internal ids as the resourceIds parameter (e.g. http://127.0.0.1:8080/local/resources?resourceIds=id1,id2,id3)

As output, we will return the list of resource ids that were successfully deleted from the local registry.

Please, take into account this two warnings:

• If the resource is shared in L1 and L2 and only the L2 resource is removed, the resource metadata will remain in the local database of Registration Handler and it will appear when getting the list of resources, since it will be still available to SymbIoTe Core.
• If the resource was shared with some federations, it will be automatically unshared, since the resource is not available in the Platform Registry any more.

2.5.3 Sharing resources to federations

Once resources are registered in the local registry, they can be shared with different federations that the platform belongs. This is done by sending a PUT request to the endpoint at /local/resources/share (e.g. http://127.0.0.1:8080/local/resources/share) whose payload is in the following format:

{
  "federationId": {
    "resourceId": boolean (bartering status)
  }
}

Where federationId is the federation identifier we want to share a resource with, resourceId is the resource internal identifier of a resource that we want to share with the federation and bartering is a boolean stating if the resource is shared by bartering or not. For example:

{
  "federation1": {
    "resource1_internalId": true,
    "resource2_internalId": false,
  }, 
  "federation2_internalId": {
     "resource1_internalId": false,
     "resource3_internalId": false,
     "resource4_internalId": true
  }
}

The output will be a JSON map whose keys are the federation identifiers and the value a list of resource metadata of the shared resources.

{
  "federation1": [
    {  
      "internalId": "resource1",
      "pluginId": "platform_01",
      "accessPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "filteringPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "resource":{
        "id": "symId1",
	    ....
      },
      "federationInfo": {
        "symbioteId": "symFedId1",
        "federation1": {
            "sharingDate": "2018-03-17T17:20:00Z",
            "bartering": true
        },
        "federation2": {
            "sharingDate": "2018-03-17T17:20:00Z",
            "bartering": false
        },
      } 
    },
    ....],
  "federation2": [
   {  
      "internalId": "resource1",
      "pluginId": "platform_01",
      "accessPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "filteringPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "resource":{
        "id": "symId1",
	    ....

      },
      "federationInfo": {
        "symbioteId": "symFedId1",
        "federation1": {
            "sharingDate": "2018-03-17T17:20:00Z",
            "bartering": true
        },
        "federation2": {
            "sharingDate": "2018-03-17T17:20:00Z",
            "bartering": false
        },
      } 
    },
   .....]
  }
}

Note that in this case, resource1 is duplicated in federation1 and federation2, as it forms part of them two and also that it contains in its metadata the information about the federations in which it's shared. If, for some reason, some resource couldn't be shared with a federation, it won't be present on the output. Errors that might have led to this will be logged in the platform log.

2.5.4 Unsharing resources from federations

Unsharing resources is done sending a DELETE request to /local/resources/share (e.g. http://127.0.0.1:8080/local/resources/share) whose body is a JSON map with keys as federation identifiers and values as list of resource internal ids. For example:

{
  "federation1" : ["resource1"],
  "federation2" : ["resource1", "resource3"]
}

The output is a map whose keys are the federation identifiers and values are list of resources metadata that were unshared.

{
  "federation1" : [
    {  
      "internalId": "resource1",
      "pluginId": "platform_01",
      "accessPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "filteringPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "resource":{
        "id": "symId1",
	    ....
      }
    }],
  "federation2": [
    {  
      "internalId": "resource1",
      "pluginId": "platform_01",
      "accessPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "filteringPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "resource":{
        "id": "symId1",
	    ....
      }
    },
    {  
      "internalId": "resource3",
      "pluginId": "platform_01",
      "accessPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "filteringPolicy": {
        "policyType": "PUBLIC",
        "requiredClaims": {}
      },
      "resource":{
        "id": "symId3",
	    ....
      }
    }]
  }
}

If for some reason a resource could not be unshared, it will not appear in the output. Errors that might have led to this will be logged in the platform log.