ICD

The CDP4-COMET Webservices expose the following endpoints or routes:

ECSS-TM-10-25 Annex C.2 - JSON REST API

The ECSS-TM-10-25 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.

HTTP Headers

A GET or POST request can include specific HTTP headers to communicate to the server what it expects the server to respond with. The following HEADERS can be used:

• Accept: The CDP4-COMET WebServices (as of Version 8.0.0) and the CDP4-COMET-SDK (as of version 24.0.0) support MessagePack serialization. The WebServices supports the following Accept headers:
  • application/json: The response is a ECSS-E-TM-10-25 JSON response that is implemeted in the Json Serializer library
  • application/msgpack: The response is a CDP4-COMET MessagePack response that is implemeted in the MessagePack Serializer library. Even though the content is encoded in MessagePack, it is 100% as the JSON content, albeit that the structure is a binary format which is more performant to serialize and deserialize.
  • In case both are provided, the response will be returned as MessagePack.
• Accept-CDP: The CDP4-COMET Web Services are able to include or exclude the CDP4-COMET extenions in the response of a GET or POST request. HTTTP headers are used to communicate to the CDP4-COMET Web Services that the client supports CDP4-COMET concepts and which version is supported. If this header is missing, only ECSS-E-TM-10-25 is returned and no CDP4-COMET extensions are inlcuded.
• User-Agent: Communications to the CDP4-COMET Web Services what kind of client is making the request (browser, CDP4-COMET SDK, etc.). The CDP4-SDK has the following as value CDP4 (ECSS-E-TM-10-25 Annex C.2) CDPServicesDal
• CDP4-Token: A correlation token that CDP4-COMET uses internally to include in log statements to track how a GET or POST request is being processed.

A response from the CDP4-COMET Web Services will always contain the following HTTP Headers:

• CDP4-Server: The header that is used to communicate the version of the server that is being used
• CDP4-Common: The header that specifies the version of the CDP4Common library that is being used
• Content-Type: The header that specifies the ECCS-E-TM-10-25 protocol and it's version. The CDP4-COMET Web Services return application/json; ecss-e-tm-10-25; version=1.0.0 while a pure E-TM-10-25 implementation only returns application/json.

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.cdp4.org/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.cdp4.org/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.cdp4.org/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.cdp4.org/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.cdp4.org/EngineeringModel/{iid}	-
[6]	GET the Iteration object, specified by its unique identifier, that is contained by the specified EngineeringModel	http[s]://cdp4services-public.cdp4.org/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.

POST requests

The CDP4-COMET Web API makes use of the POST verb to create, update and delete items. As such it is not a pure REST API since the PUT, PATCH and DELETE verbs are not supported. A POST request must be accompanied with a POST message that contains information on what items are created, updated and deleted.

The CDP4-COMET Web API accepts a POST message to the following routes:

http://hostname:port/SiteDirectory/{iid}
http://hostname:port/EngineeringModel/{iid}/iteration/{iid}

It is not possible to send POST messages to any other route, this includes an EngineeringModel route:

http://hostname:port/EngineeringModel/{iid}

Even though an EngineeringModel contains items other than Iterations, to create, update or delete these kinds of Thingss a, POST message must be sent to an Iteration that is contained by the same EngineeringModel.

A POST message is a JSON object that contains three properties also called parts; a part that contains those objects that need to be created, a part that contains the objects that need to be updated and those objects that need to be deleted. COMET® Web Services will execute the POST message as a transaction and if an operation on one of the instances fails, the whole operation or POST fails. As such the COMET® Web Services guarantee so-called transaction safety.

The post message has the following format:

{
  "_create": [],
  "_update": [],
  "_delete": []
}

Create and Update

The _create and _update properties of the transaction object (the POST message) are used to create new items and update existing items. Except for the TopContainers SiteDirectory and EngineeringModel, all the classes in the CDP4-COMET data-model are contained by another class. For instance a EmailAddress is contained by a Person. Every container has knowledge of those objects that it contains through the containment properties (composite aggregation), the contained items does not have knowledge of it's container. The result of this is that the creation of a new object also means an update on it's container. The POST message will contain the new object in the _create part, and an update to the containment property of it's container in either the _update part or the _create part. The object that is to be created must be complete, all the properties that are mandatory need to be included in the object.

Objects that are to be updated may be incomplete, only the properties of the object that are updated must be included in the _update part as well as the unique id and the classKind properties. The properties may be scalar or compound, where compound properties may be ordered or unordered. When a scalar property is updated the value of that property is replaced. When an unordered compound property is specified, the items in the collection are added to the object in the CDP4-COMET WebServices, provided that objects with those unique id's are also present in the _create part. If there are no contained objects in the _create part, the intention is to move the objects with those unique id's to the specified object, provided they exist.

The order of items in an ordered compound property is specified as a JSON object that has two properties: a key and a value. The key property is denoted with a k and the value property is denoted with a v. When the k and v properties are present in an object contained in the _update part, the key and value are added to the object in the CDP4-COMET WebServices.

{
  "k": "some key",
  "v": "some value"
}

The order of the items in an ordered compound property may be changed. This is achieved by adding an m property to the ordered item. The value of the k property is updated with the value of the m property in the CDP4-COMET WebServices. The v property must specified as well to assert that the item already exists in the ordered collection.

{
  "k": "original key",
  "m": "new key",
  "v": "existing value"
}

Delete

The _delete property of the transaction object in the POST message is used to delete Things from the CDP4-COMET WebServices. Both complete objects can be deleted or items can be removed from a compound property.

A complete object can be deleted by specifying only it's unique id iid and classKind property. The following example deletes the complete Person object.

{
  "_delete", [
    {
      "iid": "77791b12-4c2c-4499-93fa-869df3692d22",
      "classKind": "Person"
    }
  ],
  "_update": [],
  "_create": []
}

When an object with an unordered compound property is specified in the _delete part, the items in the specified property are deleted from that property in the CDP4-COMET WebServices. The following example deletes the UserPrefence object with unique id equal to 2999e725-9b19-46ec-85bf-e8d22914bad4 from the specified Person object.

{
  "_delete", [
    {
      "iid": "77791b12-4c2c-4499-93fa-869df3692d22",
      "classKind": "Person",
      "userPreference": "2999e725-9b19-46ec-85bf-e8d22914bad4"
    }
  ],
  "_update": [],
  "_create": []
}

When an object with an ordered compound property is specified in the _delete part, the items with the specified sort key(s) are deleted from the ordered compound property. Both the k and v property are specified, the v property is used to verify that the items exists for the specified k value in the ordered compound property. The following example deletes the ruleVerification object with sort-key 12345 and unique id b198ce8e-24c3-409b-ac6b-e0351de51f66 from the RuleVerificationList object:

{
  "_delete", [
    {
      "iid": "98d0c9ee-a98d-4ff0-b9b1-df8eab3a6c2f",
      "classKind": "RuleVerificationList",
      "ruleVerification": [
        { 
          "k": "12345",
          "v", "b198ce8e-24c3-409b-ac6b-e0351de51f66"
        }
      ]
    }
  ],
  "_update": [],
  "_create": []
}

CDP4-COMET Extensions

MessagePack

MessagePack is an efficient binary serialization format similar to JSON, but it's faster and smaller. The information contained in the MessagePack messages is exactly the same as the JSON format, only the encoding is different. The CDP4-COMET-SDK contains a library that provides the MessagePack serializer and deserializer. The library is used by the CDP4-COMET-WebServices as well as by the end-user applications such as the Desktop app and Web application.

The CDP4-COMET implementation depends on the open-source MessagePack-CSharp library.

Root - Welcome Page

Method	endpoint	Notes
GET	http[s]://cdp4services-public.cdp4.org/	returns a landing page that provides a description of the applicaition

POST Message - Copy Operation extension

To support copy operations server side, the CDP4-COMET API also supports a _copy part on a regular POST message. The post message has the following format:

{
  "_create": [],
  "_update": [],
  "_delete": [],
  "_copy": []
}

MORE INFORMATION COMING SOON

Long Running Tasks

CDP4-COMET supports long running tasks. These are tasks or operations that are executed in the background and do not return a result. Each POST operation to either /SiteDirectory/{id} or /EnginereeringModel{id}/Iteration/{id} in the REST API can become a long running task when its execution time exceeds the configurable maximum time a POST operation is allowed to execute. This can be configured by setting the LongRunningTasks:RetentionTime as documented in the Configuration. When a task becomes a long running task it is pushed to the background and the caller no longer has to wait for it to complete, the Task object is returned as a JSON object.

A user can request or cancel their initiated Tasks by quering the REST API:

Method	endpoint	Notes
GET	http[s]://cdp4services-public.cdp4.org/tasks	returns a list of all running tasks for the current user
GET	http[s]://cdp4services-public.cdp4.org/tasks/{id}	returns the specified tasks for the current user
POST	http[s]://cdp4services-public.cdp4.org/tasks/{id}	cancels the specified tasks for the current user

A Task object takes the following form:

{
    "id": "5217e1a4-a261-4dbe-8ce6-62910a443481",
    "requestToken": "token-string",
    "actor": "14c06d9c-9b42-417f-a438-c23ebd9a2199",
    "statusKind": "PROCESSING",
    "duration": 60,
    "startedAt": "2024-08-27T14:45:00Z",
    "finishedAt": null,
    "topContainer": "SiteDirectory",
    "revision": -1,
    "error": null
}

Seed and Restore

A CDP4-COMET WebServices instance can be seeded from an ECSS-E-TM-10-25 Annex C.3. The data that may be in the server is replaced by the contents of the Annex C.3 file. The CDP4-COMET WebServices configuration needs to be updated to enable this feature. The Annex C.3 file is POSTed to the API using the following command:

curl --form file=@"Data.zip" http(s)://<hostname>/Data/Exchange

Once the server is seeded, the data can be restored to that state by executing the following HTTP request:

GET - http(s)://hostname:port/Data/Restore

NOTE: This mechanism is used to seed or prime the server for executing the integration tests based on know data.

Export

More information coming soon

Health

The health services provide essential monitoring and management capabilities for the CDP4-COMET WebServices. These endpoints are crucial for ensuring that the application remains operational and responsive, particularly in production environments.

Method	endpoint	Notes
GET	http[s]://cdp4services-public.cdp4.org/health/startup	The startup probe is designed to determine whether the server has completed its initialization process and is ready to start accepting incoming requests. This is particularly useful during the deployment phase or after a server restart. This endpoint helps in managing the lifecycle of the application during deployment. It ensures that the application is not marked as "ready" by load balancers or orchestration tools (like Kubernetes) until all necessary services and dependencies have been properly initialized. It prevents premature traffic routing to the server, which could lead to failures or errors if the server isn't fully ready to handle requests.
GET	http[s]://cdp4services-public.cdp4.org/healthz	The liveness probe checks whether the application is still running and can respond to HTTP requests. It does not perform complex checks like database connectivity but simply verifies that the application is alive. This endpoint ensures that the application is responsive. If the liveness probe fails, it indicates that the application might be in a deadlock, crash-loop, or some other critical failure state. Monitoring this endpoint allows orchestration tools or load balancers to restart or replace instances that are unresponsive, thereby maintaining high availability.
GET	http[s]://cdp4services-public.cdp4.org/ready	The readiness probe checks whether the application is ready to process requests, specifically by verifying its ability to connect to the database and retrieve essential data. It ensures that the application's dependencies (like database connections) are properly established. This endpoint is crucial for ensuring that the application can handle traffic effectively. By checking database connectivity, it ensures that the application is not only running but also fully functional and able to perform its intended tasks. It helps prevent routing traffic to instances that are not fully ready, which could lead to errors and poor user experience.

In summary, the health services in the HealthModule are vital for maintaining the operational integrity of the application, ensuring that it can recover gracefully from failures, and providing a better overall service to users.

UserName

Method	endpoint	Notes
GET	http[s]://cdp4services-public.cdp4.org/username	sends a GET request which requires (forces) authentication and resturns the username as a string