If you review the File entity in the main $metadata document for the SampleService, you will notice there is a NavigationProperty called Representations:
https://sam.spclouddave.com/SampleService/Sppid/V2/$metadata
<EntityType Name="File"
BaseType="Com.Ingr.Core.V1.DynamicEdmEntityObject"
OpenType="true">
.
<NavigationProperty Name="Representations"
Type="Collection(Com.Ingr.Core.V1.Representation)"
ContainsTarget="true"/>
</EntityType>
A representation defines a mapping between an instance of an entity, such as a Pipe, and its graphical representation in the file.
Representations are not implemented in the SampleService. The URIs shown below will fail if you attempt to call them; the URIs demonstrate the calling conventions only.
Get entity information for a graphical representation
Representations are useful when your client application has the ability to:
-
Open a file that contains graphical objects.
-
Select or highlight a graphical object, such as a pipe.
-
Retrieve a unique ID from the graphical object, such as P-123.
Then, query for a representation:
GET https://sam.spclouddave.com/SampleService/Sppid/v2/Pipes('302')/Files('Primary 302')/Representations('P-123')
A typical response looks like:
HTTP 200 (OK)
Content-Type: application/json
{
"@odata.type": "Com.Ingr.Core.V1.Representation",
"Id": "P-123",
"EntityId": "5678",
"EntityType": "Com.Ingr.Sppid.V1.Pipe"
"EntityReadLink": "78')"
}
-
If the EntityReadLink value is not null, the client application MUST use it to read entity information.
-
If the EntityReadLink value is null, the client app inspects the $metadata document to find an entity set for the specified entity type, Pipes.
-
Request the entity data:
GET https://sam.spclouddave.com/SampleService/Sppid/v2/Pipes('5678')
Find a graphical representation of an entity
If you need to go in the reverse direction, find a graphical representation when you have the graphical file available and a particular entity instance, for example, Pipe 302:
-
The client queries the representations collection of the file to find mappings for the selected entity:
GET https://sam.spclouddave.com/SampleService/Sppid/v2/Pipes('302')/Files('Primary 302')/Representations?$filter=EntityId eq ‘5678’ and EntityType eq ‘Com.Ingr.Sppid.V1.Pipe’
HTTP 200 (OK)
Content-Type: application/json
{
"@odata.type": "Com.Ingr.Core.V1.Representation",
"Id": "1234",
"EntityId": "5678",
"EntityType": "Com.Ingr.Sppid.V1.Pipe"
"EntityReadLink": " "
}
-
The client uses representation Ids to find and highlight entity on the drawing. If more than one representation exists all will be highlighted.