Project and commit recipe

Learn how to manage projects and retrieve related commits programmatically. Each recipe includes a detailed explanation, step-by-step instructions, and code snippets.

Recipes covered:

1. Get projects

This code example demonstrates how to use Python’s requests library to interact with the SysON API and retrieve a list of projects. It sends a GET request to the API endpoint for projects, processes the response, and prints the name and ID of each project.

Example script to fetch projects:

fetch_projects.py
# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import init_sysmlv2_api

def fetch_projects(host): (2)
    projects_url = f"{host}/projects" (3)
    response = requests.get(projects_url) (4)
    if response.status_code == 200: (5)
        projects = response.json()
        for project in projects:
            print(f"Project Name: {project['name']}, ID: {project['@id']}")
    else:
        print(f"Error fetching projects: {response.status_code} - {response.text}")

if __name__ == "__main__":
    host = init_sysmlv2_api()
    # Get the projects
    fetch_projects(host)

What this code does:

1 Import required libraries:

  • requests: Used for sending HTTP requests.
2 Define the fetch_projects function with one parameter:

  • host: The base API address.
3 Constructs the API endpoint address for fetching projects.
4 Sends a GET request to the API, passing the SysON address as a query parameter.
5 Handles the API response:

  • If the projects are successfully fetched - HTTP status 200, the function prints all the projects ID and name.

  • If an error occurs, the status code and error message are displayed.

Run the script:

$ python fetch_projects.py

Output:

Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086

2. Create a new project

This recipe demonstrates how to create a new project in SysON using Python. It sends a POST request to the /projects endpoint to create a new project with a unique name and description.

Example script to create a new project:

create_project.py
# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import init_sysmlv2_api
from fetch_projects import fetch_projects
from datetime import datetime

def create_project(host, project_name): (2)
    # Define project data as query parameters
    project_params = {
        "name": project_name
    }

    # API endpoint to create a project
    url = f"{host}/projects"  (3)

    # Send POST request with query parameters
    response = requests.post(url, params=project_params)  (4)

    # Check if the project creation was successful
    if response.status_code == 201:  (5)
        response_json = response.json()
        print("Project created successfully:")
        print(f"Project ID: {response_json.get("@id", "Unknown ID")}")
        print(f"Project Name: {response_json.get('name', 'Unknown Name')}")
    else:
        print(f"Error creating project: {response.status_code} - {response.text}")

if __name__ == "__main__":
    host = init_sysmlv2_api()

    # Fetch and display the list of projects currently available on the server
    print("Fetching the list of projects currently available on the server:")
    fetch_projects(host)

    # Create a new project with a unique name by appending a timestamp
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    project_name = f"New Project - {timestamp}"
    create_project(host, project_name)

    # Fetch and display the updated list of projects after creating the new project
    print("Fetching the updated list of projects after creating a new project:")
    fetch_projects(host)

What this code does:

1 Import required libraries:

  • requests: Used for sending HTTP requests.

  • datetime: Used to generate a timestamp for unique project naming.
2 Define the create_project function with two parameters:

  • host: The base API URL.

  • project_name: The name of the project to be created.
3 Constructs the API endpoint URL of project creation.
4 Sends a POST request to the API, passing the project name as a query parameter.
5 Handles the API response:

  • If the project is successfully created - HTTP status 201, the function extracts and prints the project ID and name.

  • If an error occurs, the status code and error message are displayed.

Run the script:

$ python create_project.py

Output:

Fetching the list of projects currently available on the server:
Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Project created successfully:
Project ID: d967b937-304f-43a9-8af6-b1f3a9d6adbe
Project Name: New Project - 2024-12-31 10:52:56
Fetching the updated list of projects after creating a new project:
Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Project Name: New Project - 2024-12-31 10:52:56, ID: d967b937-304f-43a9-8af6-b1f3a9d6adbe

3. Get commits

SysON always returns a single branch with a single commit.

This example extends the functionality by fetching the commit associated with a specific project ID. It constructs an address based on the host and project ID, sends a GET request, and prints the ID of the retrieved commit.

Example script to fetch commits:

fetch_commits.py
# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import parse_arguments
from init_api import init_sysmlv2_api

def fetch_commits(host, project_id):  (2)
    commits_url = f"{host}/projects/{project_id}/commits"  (3)
    response = requests.get(commits_url)  (4)
    if response.status_code == 200:  (5)
        commits = response.json()
        for commit in commits:
            print(f"Commit ID: {commit['@id']}")
        return commits
    else:
        print(f"Error fetching commits: {response.status_code} - {response.text}")
        return None

#  Retrieves the latest commit for a given project.
def get_last_commit_id(host, project_id):
    commits = fetch_commits(host, project_id)
    if commits:
        last_commit = commits[-1] if commits else None
        if last_commit:
            last_commit_id = last_commit['@id']
            print(f"Last Commit ID: {last_commit_id}")
        return last_commit_id
    else:
        print("No commits available.")
        return None

if __name__ == "__main__":
    args = parse_arguments()
    host = init_sysmlv2_api()
    project_id = args.project_id
    fetch_commits(host, project_id)

What this code does:

1 Import required libraries:

  • requests: Used for sending HTTP requests.
2 Define the fetch_commits Function with two parameters:

  • host: The base API URL.

  • project_id: The project ID.
3 Constructs the API endpoint URL for fetching commits.
4 Sends a GET request to the API, passing the SysON address and the project ID as a query parameter.
5 Handles the API response:

  • If the projects are successfully fetched - HTTP status 200, the function prints all the projects ID and name.

  • If an error occurs, the status code and error message are displayed.

Run the script:

$ python fetch_commits.py your-project-id

Output:

Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086