Rest API: Create a commit example

[niva4959]

I hope this message finds you well.

I am currently working with SysML v2 Rest API and seeking guidance on a couple of foundational tasks:

1. How can I create a new element with a type definition (e.g., a part usage, item usage) using the SysML v2 API?
2. How can I set a new value or redefine a default value for an attribute of an element?

If there are recommended methods, code examples, or documentation references for these operations - especially for programmatic approaches via the REST API I would greatly appreciate your help.

Thank you in advance for your support!

[AxelRICHARD]

Hello,

The REST API section of the official documentation should help on this, especially the cookbook part.

Regards,

[niva4959]

Hi @AxelRICHARD , it looks like there are only examples for fetching commits, but none for creating them.

[programmingnewbie1337]

Exactly. I tried creating a project but none of the POST API calls for a commit worked for me. And theres no valid example with actual properties of how to post a commit.
This is the dummy, but i don't know how to fill the payload with valid information.

{
"@type": "string",
"change": [
{
"@type": "DataVersion",
"identity": {
"@id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"@type": "string"
},
"payload": {
"additionalProp1": {},
"additionalProp2": {},
"additionalProp3": {}
}
}
],
"description": "string"
}

[AxelRICHARD]

Hello,

Here is an example on how to create a simple PartDefinition in a simple project containing one model with only one Package.

Test on simple SysMLv2 project (id = 44ba0783-8476-442a-9ab3-b6c26e251734) with only one element: a Package named Package1 with elementId = b2426313-e795-47e8-a2b2-7e29adb12a56

All following requests can be executed in Postman or every other tool allowing to execute HTTP REST APIs.

1. Let's retrieve the elements with /elements GET request

http://localhost:8080/api/rest/projects/44ba0783-8476-442a-9ab3-b6c26e251734/commits/44ba0783-8476-442a-9ab3-b6c26e251734/elements

2. Let's add a new PartDefinition under our Package "Package1". As you may know, with SysMLv2, an Element is contained in an another Element through an intermediate Element called a Membership. In our case, an OwningMembership is the appropriate intermediate Element. So we have to add two new Elements. The containment relation between an Element and a Membership is named "ownedRelationship". The containment relation between a Membership and an Element is named "ownedRelatedElement".

2.1) Execute the /commits POST request, allowing to create the OwningMembership:

http://localhost:8080/api/rest/projects/44ba0783-8476-442a-9ab3-b6c26e251734/commits

with the following raw JSON body:

{
	"@type": "Commit",
	"change": [
		{
			"@type": "DataVersion",
			"identity": null,
			"payload": {
				"@id": "8e57348e-338f-4272-9e01-bb896784d849", **// a random ID**
				"@type": "OwningMembership"
			}
		},
		{
			"@type": "DataVersion",
			"identity": {
				"@id":"b2426313-e795-47e8-a2b2-7e29adb12a56", **// Package1 elementId**
				"@type" : "DataIdentity"
			},
			"payload": {
				"@id": "f3d97864-09f0-4af7-95bd-44b1a3243fdb", **// a random ID**
				"@type": "OwningMembership",
				"ownedRelationship": [{
					"@id": "8e57348e-338f-4272-9e01-bb896784d849" **// the random ID used by the creation of the OwningMembership**
				}]
			}
		}
	]
}

The JSON response:

{
	"@id": "44ba0783-8476-442a-9ab3-b6c26e251734",
	"@type": "Commit",
	"created": "1970-01-01T00:00:00Z",
	"description": "The one and only commit for this project",
	"owningProject": {
		"@id": "44ba0783-8476-442a-9ab3-b6c26e251734"
	},
	"previousCommits": []
}

2.2) Execute the /elements GET request, allowing to get the "elementId" of the new OwningMembership that will be the container of our new PartDefinition:

http://localhost:8080/api/rest/projects/44ba0783-8476-442a-9ab3-b6c26e251734/commits/44ba0783-8476-442a-9ab3-b6c26e251734/elements

[
	{
		"@id": "1de6b808-b97b-44ba-87ca-0ed2d196a066",
		"@type": "Package",
		"elementId": "44ba0783-8476-442a-9ab3-b6c26e251734",
		...
	},
	{
	"@id": "6de942db-fe39-45ad-8db4-d980955891c2",
	"@type": "OwningMembership",
	"aliasIds": "[]",
	"declaredName": null,
	"declaredShortName": null,
	"elementId": "a0dc4f1f-0646-46c4-81f4-1b91f9ac1915", **// The property we need**
	...
]

2.3) Now we have the "elementId" of our new OwningMembership, we can create a new PartDefinition under it.

Execute the /commits POST request, allowing to create the PartDefinition:

http://localhost:8080/api/rest/projects/44ba0783-8476-442a-9ab3-b6c26e251734/commits

with the following raw JSON body:

{
	"@type": "Commit",
	"change": [
		{
			"@type": "DataVersion",
			"identity": null,
			"payload": {
				"@id": "4d4596e7-27a3-493a-8c6a-de63dddfca2b", **// random ID**
				"@type": "PartDefinition",
				"declaredName": "MyRESTNewPartDef"
			}
		},
		{
			"@type": "DataVersion",
			"identity": {
				"@id":"a0dc4f1f-0646-46c4-81f4-1b91f9ac1915", **//OwningMembership elementId**
				"@type" : "DataIdentity"
			},
			"payload": {
				"@id": "aff1e118-af4b-465d-b9a9-8a407017d4d2",
				"@type": "PartDefinition",
				"ownedRelatedElement": [{
					"@id": "4d4596e7-27a3-493a-8c6a-de63dddfca2b" **// the random ID used by the creation of the PartDefinition**
				}]
			}
		}
	]
}

The JSON response:

{
	"@id": "5ec64279-b533-461d-bdb4-2ac5de399710",
	"@type": "Commit",
	"created": "1970-01-01T00:00:00Z",
	"description": "The one and only commit for this project",
	"owningProject": {
		"@id": "5ec64279-b533-461d-bdb4-2ac5de399710"
	},
	"previousCommits": []
}

3. Finally, retrieve the elements one last time with /elements GET request to confirm the new Elements have been added by the POST requests.

http://localhost:8080/api/rest/projects/44ba0783-8476-442a-9ab3-b6c26e251734/commits/44ba0783-8476-442a-9ab3-b6c26e251734/elements

Hope it will help you!

Regards,

[programmingnewbie1337]

Thanks for that one!
Is there an overall overview explanation for the JSON notations and attributes and how all of the elements are related to each other?
Im writing my master thesis about this and this would be a great help.

[AxelRICHARD]

Yes it is detailed in the SysMLv2 specification, and also in the SysON metamodel.