Introduction
The following highlights the basic operations that can be performed via the public API on the platform's objects. For more details on the endpoints, see Swagger
Creating an entity
Creating or registering an entity is done in two phases: first the entity skeleton is created, and then the metadata is completed through editing. This is because, due to the complexity of native entities, creation only allows setting the primary fields and keys. If only the basic information is needed, then the first step will be sufficient.
Creating the entity
Step 1. Create the entity skeleton.
Generates the entity with the fundamental values (name, OU, and PKs) and includes the necessary internal relationships (for example, in the case of an instance, with a process and a solution).
POST https://{{host}}/gateway/api/v4/entity/create/{objectSubType}
At this stage, only the primary fields and keys can be set. The rest of the metadata is completed during the editing phase.
Editing the entity
Step 2. Query the dynamic form structure.
Serves as a reference for building the input data for the modification. Returns the form structure along with its validations.
GET https://{{host}}/gateway/api/v4/catalog/entity/{objectSubType}
Step 3 (optional). Query the full list of validations.
Also includes the only-on-edition validations.
GET https://{{host}}/gateway/api/v4/catalog/complete/entity/{objectSubType}
Step 4 (optional). Query the structure of a specific entity.
Returns the fields and validations of a specific object.
GET https://{{host}}/gateway/api/v4/catalog/entity/{objectSubType}/{idObject}
Step 5. Send the list of attributes to modify the entity.
Editing requires sending a list of attributes with the metadata modification.
POST https://{{host}}/gateway/api/v2/entity/save/{objectSubType}/{idObject}
Editing behavior
-
If the object is in DRAFT status: the previous values are modified directly.
-
If the object is in APPROVED, DEPRECATED, or EXPIRED status: a new DRAFT is created with a new ID, cloning everything necessary (for example, the datasetfield entries in a DATASET or the dataset relationships in a DSA) and leaving the original object intact.
Just as from the portal, the submitted data is validated and the entity is only edited if all validations are passed.
Validation
Once editing is complete, the following endpoint is required to submit the entity for validation.
POST https://{{host}}/gateway/api/v2/entity/submit/{objectSubType}/{idObject}
Creating a relationship
As with entities, working with relationships relies on the dynamic form as a reference for building the input data. Unlike the entity, the relationship is created directly by sending the list of attributes (there is no prior skeleton phase).
Creating a relationship
Step 1. Query the dynamic form structure.
Allows you to find out which attributes the template of the relationship to be created has. Returns the form structure with the relationship's fields and their validations.
GET https://{{host}}/gateway/api/v4/catalog/relationship/{objectSubType}
Step 2. Send the list of attributes to create the relationship.
Creation requires sending a list of attributes. Since this is a creation, the name must be included as an attribute of the object.
POST https://{{host}}/gateway/api/v2/relationship/create/{objectSubType}
The created relationship will always be in DRAFT status. Just as from the portal, the data is validated and the relationship is only created if all validations are passed.
Editing a relationship
Step 3. Query the dynamic form structure of the specific relationship.
Serves as a reference for building the modification data. Returns the relationship's fields and their validations.
GET https://{{host}}/gateway/api/v4/catalog/relationship/{objectSubType}/{idObject}
Step 4. Send the list of attributes to modify the relationship.
Editing requires sending a list of attributes with the metadata modification.
POST https://{{host}}/gateway/api/v2/relationship/save/{objectSubType}/{idObject}
Editing behavior
-
If the relationship is in DRAFT status: the previous values are modified directly.
-
If the relationship is in APPROVED, DEPRECATED, or EXPIRED status: a new DRAFT is created with a new ID, leaving the original object intact.
Just as from the portal, the submitted data is validated and the relationship is only edited if all validations are passed.
Validation
Once editing is complete, the following endpoint is required to submit the relationship for validation.
POST https://{{host}}/gateway/api/v2/relationship/submit/{objectSubType}/{idObject}
Other operations
Getting all relationships of an entity
Allows you to obtain all the relationships that an entity has, including internal relationships. It consists of the following call:
GET https://{{host}}/gateway/api/v2/relationship/all/{objectSubtype}/{id}
Getting the defined values for an attribute
Allows you to obtain all possible values of an attribute with predefined values of type SELECT. It consists of the call:
POST https://{{host}}/gateway/api/v2/attribute/values