Annex C - STARIONGROUP/COMET-IME-Community-Edition GitHub Wiki

Introduction

ECSS-E-TM-10-25A Annex C specifies the implementation technology that is required to exchange data that complies with the data model specified in ECSS-E-TM-10-25A Annex A. Annex C prescribes 2 technologies that need to be supported by an implementation for it to be fully compliant with ECSS-E-TM-10-25A:

CDP4-COMET is fully compliant with the standard. The CDP4-COMET-SDK can be used to create applications client and server side that implement the JSON REST API. It also provides an implementation of to read from and write a file that conforms to the JSON Exchange File Format. The CDP4-COMET Desktop application can communicate with a JSON REST API, of which the COMET Web Services are an implementation. The CDP4-COMET Web Services can export data to a JSON Exchange File Format and can be seeded from a JSON Exchange File Format.

JSON REST API

The JSON REST API is a particular flavor of REST. Two HTTP verbs are supported: GET and POST, DELETE, PUT and PATCH are not supported. GET requests are used to retrieve data. POST requests are used to create, update and delete data; multiple operations are supported in one POST request, allowing an API user to add, update and delete different objects with one request.

GET requests

In order to retrieve data from a server a GET request must be performed. A GET request is performed along the containment hierarchy specified by Annex A. Annex A provides two so-called TopContainer classes, the SiteDirectory and EngineeringModel. The GET requests can only be performed on either the SiteDirectory and EngineeringModel URI's. The subsequent parts of the URI follow the aggregate composition properties of Annex A. To GET a specific Thing the unique identifier, represented by the {iid} token, needs to be specified as well. The {iid} token must be a valid UUID version 4.

nr. Method Request Notes
[1] GET the singleton SiteDirectory object http[s]://cdp4services-public.rheagroup.com/SiteDirectory[/*] Specifying * is not mandatory but allowed and will return the same result
[2] GET the singleton SiteDirectory object specified by its unique identifier http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid} The unique identifier can be retrieved using [1]
[3] Get the email address of a person contained in the SiteDirectory http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid}/person/{iid}/email/{iid} Note that person and email are all lower-case
[4] Get all the email addresses of a person contained in the SiteDirectory http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid}/person/{iid}/email[/*] the /* is not mandatory but allowed and will return the same result as when not provided
[5] GET an EngineeringModel specified by its unique identifier http[s]://cdp4services-public.rheagroup.com/EngineeringModel/{iid} -
[6] GET the Iteration object, specified by its unique identifier, that is contained by the specified EngineeringModel http[s]://cdp4services-public.rheagroup.com/EngineeringModel/{iid}/iteration/{iid} Note that iteration is a property of the EngineeringModel and that it is provided with lower-case.

The result of a GET request is JSON array of JSON objects that represent ECSS-E-TM-10-25 Annex A objects. The ClassKind property of the Thing class denotes its type and is used for serialization and deserialization purposes.

Annex C also supports query parameters. These query parameters are used to either narrow or widen the scope of the expected result. The following query parameters are supported and may be used in combination, unless specified otherwise:

parameter value description Combination
revisionNumber an integer value greater than or equal to zero Returns the set of all objects contained by the object specified in the URI, that have a revisionNumber that is greater than the given value. This enables getting the net change of objects since a previous revision. Note: Specifying revisionNumber=0 is equivalent to specifying extent=deep. revisionNumber=n may only be used as a single query parameter, no combination with other query parameters shall be allowed nor supported.
extent shallow (default value) or deep when deep is specified the requested object including all the objects contained by it along the complete containment tree includeReferenceData, includeAllContainers, includeFileData
includeReferenceData false (default value) or true For a request on a SiteDirectory return all contained reference data objects. For a request on an EngineeringModel return all reference data objects from the chain of required ReferenceDataLibrary objects referenced by that EngineeringModel, as defined through the requiredRdl properties. extent, includeAllContainers, includeFileData
includeAllContainers false (default value) or true In addition to the requested object, return all containers in the containing composite structure from the lowest level specified in the URI up to the top container. extent, includeReferenceData, includeFileData
includeFileData false (default value) or true In addition to the requested object(s), return all data associated with FileRevision objects (i.e. file content) in the (multi-part) reply. extent, includeReferenceData, includeAllContainers

NOTE: Even though the includeReferencaData query parameter is provided it is not recommended to use this when performing a GET request on an Iteration in an EngineeringModel. From the URI of the GET request it is possible to determine what Iteration instance the response is related to. This is useful when determining the containment tree in client applications of said data since the unique identifiers of objects contained in Iterations is not truly unique across the Iterations in an EngineeringModel. When Reference Data is returned as well it may become difficult to determine to what containment tree this data belongs, not so much for the reference data itself, but for concepts such as Alias, Definition and Hyperlink, these classes may be contained by data in the EngineeringModel containment tree and SiteDirectory Tree.

More information coming soon

POST requests

More information coming soon

Side Effects

More information coming soon

JSON Exchange File Format

More information coming soon