Helix IPLM public API

The Helix IPLM API provides a powerful capability to directly access and manipulate objects and features within the IPLM platform. IP creation, deletion, query, and cataloging are all supported through the API.

API Swagger documentation

This page offers an overview on how to use the API. See the full Swagger documentation that covers all the capabilities the API currently supports on PiServer itself. The address of the API documentation is configured using the PIAPI_DOCS_URI in the IPLM web configuration file. See IPLM Web configuration for more information.

API functionality overview

The public API can be used for automation and scripting instead of PiCLI, because the public API offers the best performance available on the platform and it is versioned, so it remains stable over time.

The API can be used for the following tasks:

  • IP creation, deletion, query, and cataloging

  • Admins can edit the Library field of an IP to move it to a different Library. See Renaming IPs for information on the other fields that must be migrated.

  • Users can edit the source field on a line to indicate which IPV the line was copied or branched from

Getting started

For the context of this document, base_url refers to the port and address where PiServer is hosted.

base_url 
http://localhost:8080

Login to Helix IPLM

POST {base_url}/login 
{
      "username": "admin",
      "password": "admin"
}
  • What happens?
    • User is logged in and a session is started. An access_token is returned in the following way. 
200 Successful Login Response 
{
      "access_token": "2989006a-2fbc-46fd-ad41-0341817eadd4"
}
  • Equivalent CLI command:
  • Additional notes:
    • This access token now needs to be added as part of the Authorization Header of the requests to follow. Most of the requests made to the public API require this token to validate information about the user (license, permissions, session timeout, etc...)
    • More information can be found in the endpoint reference documentation.

Creating Libraries

Minimum body to create a Library:

POST {base_url}/public/v1/libraries 
{
      "name": "food"
}
  • What happens?
    • The Library food is created
  • Equivalent CLI command:

Creating new IPs

Minimum body to create a Container type IP:

POST {base_url}/public/v1/iplvs 
{
      "ip": {
        "description": "Bacon is food",
        "dm_type_name": "CONT",
        "library_id": "7e8699db-eae0-4449-af64-cea83c8679e5",
        "name": "bacon"      },
      "ipv": {
        "version_message": "First version of bacon in food library"      }
}
  • What happens?
    The following objects are created:
    • IP: food.bacon
    • IP Line: food.bacon@.TRUNK
    • IP Version: food.bacon@0.TRUNK
  • Equivalent CLI command:

  • Additional notes:

    • Different from the CLI, property_values for both the IP and IPV can be set upon creation. The specified value will remain hidden until the property is attached to the IP and/or IPV.

Viewing IP Hierarchy

GET {base_url}/public/v1/ipvs/80060818-a361-4d59-a4c4-9b9d79153b68/tree
Click here to expand code:Closed
{
  "metadata": {
    "status_code": 200,
    "timestamp": 1596736704066,
    "duration": 17
  },
  "data": {
    "tree": [
      {
        "id": "0410ff73-d6dc-4f9f-884f-abdafd283ec9",
        "uc": 1,
        "fqn": {
          "library": "drinks",
          "ip": "beer",
          "line": "TRUNK",
          "version": 1
        },
        "ipl": {
          "id": "08a3bdbd-888d-4440-8c86-5d4f0ce317ae",
          "href": "/public/v1/ipls/08a3bdbd-888d-4440-8c86-5d4f0ce317ae",
          "fqn": {
            "line": "TRUNK",
            "ip": "beer",
            "library": "drinks"          }
        },
        "version_message": "Version one",
        "repo_path": "//depot/drinks/beer/trunk",
        "icon": "",
        "project_props": [],
        "resources": [],
        "forbidden_resource_count": 0,
        "contents": {
          "id": "f11de326-f983-4d09-949b-c76666ee7535",
          "href": "/public/v1/ipv-contents/f11de326-f983-4d09-949b-c76666ee7535"        },
        "current_aliases": [
          {
            "id": "c7846bdf-a4af-40d3-a34d-33541de54353",
            "href": "/public/v1/aliases/c7846bdf-a4af-40d3-a34d-33541de54353",
            "name": "HEAD"          },
          {
            "id": "f1fdf274-2d96-4d19-9d27-4da71c0e67ab",
            "href": "/public/v1/aliases/f1fdf274-2d96-4d19-9d27-4da71c0e67ab",
            "name": "LATEST"          }
        ],
        "historic_aliases": [],
        "attributes": [],
        "property_values": []
      },
      {
        "id": "f17dc73b-22a7-4808-9730-628f0af88047",
        "uc": 1,
        "fqn": {
          "library": "drinks",
          "ip": "vodka",
          "line": "TRUNK",
          "version": 2
        },
        "creator": {
          "id": "e06c4716-d15c-4d06-967a-f67d4e06a136",
          "href": "/public/v1/users/e06c4716-d15c-4d06-967a-f67d4e06a136",
          "name": "admin"        },
        "creation_timestamp": 1596736646636,
        "ipl": {
          "id": "806bbca7-7246-4288-8d15-eeb85a14cc8f",
          "href": "/public/v1/ipls/806bbca7-7246-4288-8d15-eeb85a14cc8f",
          "fqn": {
            "line": "TRUNK",
            "ip": "vodka",
            "library": "drinks"          }
        },
        "version_message": "Version one",
        "repo_path": "//depot/vodka/trunk",
        "icon": "",
        "project_props": [],
        "resources": [
          {
            "ipv": {
              "id": "0410ff73-d6dc-4f9f-884f-abdafd283ec9",
              "href": "/public/v1/ipvs/0410ff73-d6dc-4f9f-884f-abdafd283ec9",
              "fqn": {
                "library": "drinks",
                "ip": "beer",
                "line": "TRUNK",
                "version": 1
              }
            },
            "private_resource": false
          }
        ],
        "forbidden_resource_count": 0,
        "contents": {
          "id": "89d5f65d-17a6-4d2e-ac7f-37af399cd9e8",
          "href": "/public/v1/ipv-contents/89d5f65d-17a6-4d2e-ac7f-37af399cd9e8"        },
        "current_aliases": [
          {
            "id": "5c18fdef-8b0c-4097-899b-0e1ae96153a3",
            "href": "/public/v1/aliases/5c18fdef-8b0c-4097-899b-0e1ae96153a3",
            "name": "LATEST"          },
          {
            "id": "47e50ddc-abb5-497f-adbd-028540fd4738",
            "href": "/public/v1/aliases/47e50ddc-abb5-497f-adbd-028540fd4738",
            "name": "HEAD"          }
        ],
        "historic_aliases": [],
        "attributes": [],
        "property_values": []
      },
      {
        "id": "7b1dc036-ac64-4434-86bd-83af873622be",
        "uc": 1,
        "fqn": {
          "library": "food",
          "ip": "olive",
          "line": "TRUNK",
          "version": 1
        },
        "ipl": {
          "id": "a9a5a15c-e55e-4e1d-8eb9-b7d4af900d0f",
          "href": "/public/v1/ipls/a9a5a15c-e55e-4e1d-8eb9-b7d4af900d0f",
          "fqn": {
            "line": "TRUNK",
            "ip": "olive",
            "library": "food"          }
        },
        "version_message": "Version one",
        "repo_path": "//depot/olive/trunk",
        "icon": "",
        "project_props": [],
        "resources": [],
        "forbidden_resource_count": 0,
        "contents": {
          "id": "d056b8cb-aab9-4119-9256-1bd3f2b2e6f9",
          "href": "/public/v1/ipv-contents/d056b8cb-aab9-4119-9256-1bd3f2b2e6f9"        },
        "current_aliases": [],
        "historic_aliases": [],
        "attributes": [],
        "property_values": []
      },
      {
        "id": "80060818-a361-4d59-a4c4-9b9d79153b68",
        "uc": 1,
        "fqn": {
          "library": "drinks",
          "ip": "vodka_martini",
          "line": "TRUNK",
          "version": 2
        },
        "creator": {
          "id": "e06c4716-d15c-4d06-967a-f67d4e06a136",
          "href": "/public/v1/users/e06c4716-d15c-4d06-967a-f67d4e06a136",
          "name": "admin"        },
        "creation_timestamp": 1596736669249,
        "ipl": {
          "id": "1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "href": "/public/v1/ipls/1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "fqn": {
            "line": "TRUNK",
            "ip": "vodka_martini",
            "library": "drinks"          }
        },
        "version_message": "Version one",
        "icon": "",
        "project_props": [],
        "resources": [
          {
            "alias": {
              "id": "47e50ddc-abb5-497f-adbd-028540fd4738",
              "href": "/public/v1/aliases/47e50ddc-abb5-497f-adbd-028540fd4738",
              "name": "HEAD"            },
            "ipv": {
              "id": "f17dc73b-22a7-4808-9730-628f0af88047",
              "href": "/public/v1/ipvs/f17dc73b-22a7-4808-9730-628f0af88047",
              "fqn": {
                "library": "drinks",
                "ip": "vodka",
                "line": "TRUNK",
                "version": 2
              }
            },
            "private_resource": false
          },
          {
            "ipv": {
              "id": "7b1dc036-ac64-4434-86bd-83af873622be",
              "href": "/public/v1/ipvs/7b1dc036-ac64-4434-86bd-83af873622be",
              "fqn": {
                "library": "food",
                "ip": "olive",
                "line": "TRUNK",
                "version": 1
              }
            },
            "private_resource": false
          }
        ],
        "forbidden_resource_count": 0,
        "current_aliases": [
          {
            "id": "fff4d314-3ab0-49c7-8b33-ad87e7f769d4",
            "href": "/public/v1/aliases/fff4d314-3ab0-49c7-8b33-ad87e7f769d4",
            "name": "HEAD"          },
          {
            "id": "c4073d24-4f7a-4059-af09-268496b4491e",
            "href": "/public/v1/aliases/c4073d24-4f7a-4059-af09-268496b4491e",
            "name": "LATEST"          }
        ],
        "historic_aliases": [],
        "attributes": [],
        "property_values": []
      }
    ]
  },
  "links": {}
}

Reconstruct a tree

1. Start from the IPV that the GET ipvs/{id}/tree requests was made. In this example, the IPV is:

   drinks.vodka_martini@1.TRUNK; 80060818-a361-4d59-a4c4-9b9d79153b68

2. See the list of resources for this IPV. In this example, the resources are:

   drinks.vodka@HEAD.TRUNK; 47e50ddc-abb5-497f-adbd-028540fd4738 [@2; f17dc73b-22a7-4808-9730-628f0af88047]
   food.olive@1.TRUNK; 7b1dc036-ac64-4434-86bd-83af873622be

3. For each resource IPV, see the list of its resources. In this example, 

drinks.vodka@2.TRUNK has resource:

   drinks.beer@1.TRUNK; 0410ff73-d6dc-4f9f-884f-abdafd283ec9

This resource has no resources, the leaf node is reached from this resource. 

food.olive@1.TRUNK does not have a resource. Which means, the leaf node is reached from this resource as well.  

For each resource, steps 2 and 3 should be repeated until the leaf node is reached

The final tree is:

GET {base_url}/public/v1/ipvs/80060818-a361-4d59-a4c4-9b9d79153b68/tree 
drinks.vodka_martini@2.TRUNK
├─ drinks.vodka@HEAD.TRUNK [@2]
│  └─ drinks.beer@1.TRUNK
└─ food.olive@1.TRUNK

  • Equivalent CLI command:

Workspaces and releases

Workspaces

  • Workspaces cannot be loaded using the public API. The only available command is to read the workspaces. More information can be found in the endpoint reference documentation.

  • Equivalent CLI command:

Releases

  • Currently the only Server Side releases are supported

Snapshots

  • Snapshots are not supported in the public API

Attaching / Detaching objects to parent objects

The main object in the endpoint path is the parent object – the target object to which child objects are being attached to or being detached from – and the id that follows refers to the parent object's id. The second object on the path refers to the child object – the object being attached / detached.

HTTP Request Endpoint Parent Object Child Object Additional Notes
GET http://{base_url}/public/v1/groups/{id}/groups Group Group Attaches a list of group IDs to be the subgroup of a parent group.
DELETE http://{base_url}/public/v1/groups/{id}/groups/{child_group_id} Detaches the child group (second id on the path) from the parent group (first id on the path)
GET http://{base_url}/public/v1/groups/{id}/users User Attaches a list of user IDs to be users part of a parent group.
DELETE http://{base_url}/public/v1/groups/{id}/users/{user_id} Detaches the user (second id on the path) from the parent group (first id on the path)
POST http://{base_url}/public/v1/ipls/{id}/attributes IP Lines Attributes Creates or attaches an attribute to an IP Line. If the attribute doesn't exist, a new attribute with the specified value is created and attached. Otherwise it updates the value of the already existing and attached attribute with the specified value.
POST http://{base_url}/public/v1/ips/{id}/labels IPs
 Labels Attaches a list of label IDs to an IP.
DELETE http://{base_url}/public/v1/ips/{id}/labels/{label_id} Detaches the label (second id on the path) from the IP (first id on the path)
POST http://{base_url}/public/v1/ips/{id}/attributes Attributes Creates or attaches an attribute to an IP. If the attribute doesn't exist, a new attribute with the specified value is created and attached. Otherwise it updates the value of the already existing and attached attribute with the specified value.
POST http://{base_url}/public/v1/ips/{id}/property-sets Property Sets Attaches a list of property set IDs to an IP.
DELETE http://{base_url}/public/v1/ips/{id}/property-sets/{property_set_id} Detaches the property set (second id on the path) from the IP (first id on the path)
POST http://{base_url}/public/v1/ipvs/{id}/aliases IPVs
 Aliases Creates or attaches the alias to the IPV. For unique aliases, set the unique field to true.
DELETE http://{base_url}/public/v1/ipvs/{id}/aliases/{alias_id} Detaches or deletes – if it's the last one on the IPV or IP for unique aliases – the alias from the IPV
POST http://{base_url}/public/v1/ipvs/{id}/attributes Attributes Creates or attaches an attribute to an IPV. If the attribute doesn't exist, a new attribute with the specified value is created and attached. Otherwise it updates the value of the already existing and attached attribute with the specified value.
POST http://{base_url}/public/v1/libraries/{id}/attributes Libraries


 Attributes Creates or attaches an attribute to a Library. If the attribute doesn't exist, a new attribute with the specified value is created and attached. Otherwise it updates the value of the already existing and attached attribute with the specified value.
POST http://{base_url}/public/v1/libraries/{id}/property-sets Property Sets Attaches a list of property set IDs to a Library.
DELETE http://{base_url}/public/v1/libraries/{id}/property-sets/{property_set_id} Detaches the property set (second id on the path) from the Library (first id on the path)
POST http://{base_url}/public/v1/libraries/{id}/labels Labels Attaches a list of label IDs to a Library.
DELETE http://{base_url}/public/v1/libraries/{id}/labels/{label_id}
Detaches the label (second id on the path) from the Library (first id on the path)
POST http://{base_url}/public/v1/property-sets/{id}/property-definitions Property Sets Property Definitions Attaches a list of property definition IDs to a Property Set.
DELETE http://{base_url}/public/v1/property-sets/{id}/property-definitions/{property_definition_id} Detaches the property definition (second id on the path) from the Property Set (first id on the path)
POST http://{base_url}/public/v1/queries/{id}/attributes Queries Attributes Creates or attaches an attribute to a Query. If the attribute doesn't exist, a new attribute with the specified value is created and attached. Otherwise it updates the value of the already existing and attached attribute with the specified value.

Attaching an attribute to an IP

POST {base_url}/public/v1/ips/dcd01392-a267-42ab-ae09-1360f0478e4f/attributes
{
  "name": "ip_attribute",
  "value": "ValueForTheIpAttribute"}
  • What happens?
    • The attribute ip_attribute is created and attached to the IP drinks.vodka_martini
  • Equivalent CLI command:

    • pi attr set drinks.vodka_martini ip_attribute ValueForTheIpAttribute

GET {base_url}/public/v1/ips/dcd01392-a267-42ab-ae09-1360f0478e4f

Click here to expand code:Closed

{
  "metadata": {
    "status_code": 200,
    "timestamp": 1596751398830,
    "duration": 13
  },
  "pagination_data": {
    "start_index": 0,
    "limit": 10000,
    "total_count": 1
  },
  "data": [
    {
      "id": "dcd01392-a267-42ab-ae09-1360f0478e4f",
      "uc": 2,
      "fqn": {
        "ip": "vodka_martini",
        "library": "drinks"      },
      "library": {
        "id": "1a156c70-82be-4ea9-b9fc-7fdaa6e9829f",
        "href": "/public/v1/libraries/1a156c70-82be-4ea9-b9fc-7fdaa6e9829f",
        "fqn": {
          "library": "drinks"        }
      },
      "description": "a martini with food and drinks",
      "icon": "",
      "dm_type": {
        "id": "ef9f82f9-24e4-4177-ac07-aa82ea3d21b0",
        "href": "/public/v1/dm-types/ef9f82f9-24e4-4177-ac07-aa82ea3d21b0",
        "name": "Container"      },
      "host": "",
      "hooks": {
        "hook_post_load": "",
        "hook_post_update": "",
        "hook_pre_release": "",
        "hook_post_release": "",
        "hook_pre_integrate": "",
        "hook_post_integrate": ""      },
      "labels": [],
      "ipls": [
        {
          "id": "1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "href": "/public/v1/ipls/1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "fqn": {
            "line": "TRUNK",
            "ip": "vodka_martini",
            "library": "drinks"          }
        }
      ],
      "attributes": [
        {
          "id": "abec0779-221a-4fe8-837c-4b60963c50af",
          "href": "/public/v1/attributes/abec0779-221a-4fe8-837c-4b60963c50af",
          "name": "ip_attribute"        }
      ],
      "property_values": [],
      "property_sets": [],
      "perms": []
    }
  ],
  "links": {}
}

Attaching an Attribute to an IP

POST {base_url}/public/v1/ips/dcd01392-a267-42ab-ae09-1360f0478e4f/attributes
{
  "name": "ip_attribute",
  "value": "ValueForTheIpAttribute"}
  • What happens?
    • The attribute ip_attribute is created and attached to the IP drinks.vodka_martini
  • Equivalent CLI command:

    • pi attr set drinks.vodka_martini ip_attribute ValueForTheIpAttribute

GET {base_url}/public/v1/ips/dcd01392-a267-42ab-ae09-1360f0478e4f

Click here to expand code:Closed

{
  "metadata": {
    "status_code": 200,
    "timestamp": 1596751398830,
    "duration": 13
  },
  "pagination_data": {
    "start_index": 0,
    "limit": 10000,
    "total_count": 1
  },
  "data": [
    {
      "id": "dcd01392-a267-42ab-ae09-1360f0478e4f",
      "uc": 2,
      "fqn": {
        "ip": "vodka_martini",
        "library": "drinks"      },
      "library": {
        "id": "1a156c70-82be-4ea9-b9fc-7fdaa6e9829f",
        "href": "/public/v1/libraries/1a156c70-82be-4ea9-b9fc-7fdaa6e9829f",
        "fqn": {
          "library": "drinks"        }
      },
      "description": "a martini with food and drinks",
      "icon": "",
      "dm_type": {
        "id": "ef9f82f9-24e4-4177-ac07-aa82ea3d21b0",
        "href": "/public/v1/dm-types/ef9f82f9-24e4-4177-ac07-aa82ea3d21b0",
        "name": "Container"      },
      "host": "",
      "hooks": {
        "hook_post_load": "",
        "hook_post_update": "",
        "hook_pre_release": "",
        "hook_post_release": "",
        "hook_pre_integrate": "",
        "hook_post_integrate": ""      },
      "labels": [],
      "ipls": [
        {
          "id": "1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "href": "/public/v1/ipls/1468371e-f1bd-40b7-9bcc-d5f87395b17a",
          "fqn": {
            "line": "TRUNK",
            "ip": "vodka_martini",
            "library": "drinks"          }
        }
      ],
      "attributes": [
        {
          "id": "abec0779-221a-4fe8-837c-4b60963c50af",
          "href": "/public/v1/attributes/abec0779-221a-4fe8-837c-4b60963c50af",
          "name": "ip_attribute"        }
      ],
      "property_values": [],
      "property_sets": [],
      "perms": []
    }
  ],
  "links": {}
}

FAQs

What's the difference between an IPV object and an IPLV object?

An IPLV object contains an IPV object. An IPLV object consists of its corresponding IP, IPL and IPV objects. One can think of it as simply an IPV with detailed information about its parent IP Line and parent IP. 

How do I create a new IP object?

Use the POST method of an IPLV object. This endpoint guarantees the required dependencies between the IP, IPL and IPV objects. See example above, under IPLVs.

Where do my attached and set attributes, property values, labels appear?

Attributes, Property Values, and Labels are considered metadata of the object they are attached to. The value set can be found by fetching information of the main target object itself.

How do I set a property value for a given IP?

  1. Create a property set
    i.e. POST {base_url}/public/v1/property_sets

  2. Create a property definition
    i.e. POST {base_url}/public/v1/property-definitions

  3. Attach the property definition to the property set
    i.e. POST {base_url}/public/v1/property-sets/{id}/property-definitions, where id = id of the property set

    In the body of the POST request, input the ids of the property definition that you'd like to attach to the property set, i.e.

    { "ids": ["propdef_1_ID", "propdef_2_ID", "propdef_3_ID", ...] }

  4. Attach the property set containing the property definition to the target IP
    i.e. POST {base_url}/public/v1/ips/{id}/property-sets, where id = id of the target IP

    In the body of the POST request, input the ids of the property sets that you'd like to attach to the target IP, i.e.

    { "ids": ["propset_1_ID", "propset_2_ID", "propset_3_ID", ...] }
  5. Edit the 'property_values' parameter of the target IP or IPV in its respective fields 
    i.e. PUT {base_url}/public/v1/iplvs/{id}