API: Generic Data Service
Details
Generic Data Service introduces an approach to work with the Product data over the REST Web Services. The Service delivers the basic methods to be able to fulfill any operation with the data like CRUD-operations (Create-Read-Update-Delete). The methods are generic, which means, it fully relies on the state of the Product Schema and allows to work with any Configuration item or Data Definition presented in the Product Schema. That approach allows extending the Schema with new entities, or customize the present ones, and then immediately dealing with new artifacts via Web Services.
The Generic Data Service differentiates two dedicated Web Services
- "Objects" (/api/data/objects) which addresses operations with the Objects (instances of the Configuration Items)
- "Fragments" (/api/data/fragments), provides the operation for working with the Fragments (Instances of the Data Definitions)
Security
The Generic Data Service provides all mechanisms for reading and modifying any data in the Production database. To prevent the compromising the Application security, the Generic Data Service supports multi-level Authorization mechanism, which allows easily configure the minimal permissions which required for the implementing the Integration.
1. Authentication
The Generic Data Service methods can be executed only by the Authenticated user. The System provides several approaches to authenticate the Web Service caller. For more details, please see How to make a Web Service method call.
2. Check the Audience
All Web Services hosted in Solution Builder Service Layer uses the "Audience" for the Web Service Methods Authorization. The Web Service Operation Audience is the group of people, who are allowed to execute this Web Service Operation. If the caller is not allowed to execute the Operation, the System returns Forbidden (403) error. For more details on how to set up the Audience, please see How to Set Audience in Solution Builder.
In default Product configuration the execution of all Generic Data Service Operations is granted exclusively for the Administration group. Please configure the Audience appropriately for the Operations you want to use in "Integrations"
3. Configuration Item Permission
The System uses the Configuration Items Permissions configuration to regulate the accessibility of the data for the user. For more details see the CRUD Security Management in UUX
Best Practice: Configuring the Security
To mitigate the risk of the System vulnerability it is recommended to configure the minimal required permissions for the Generic Data Service. The following example explains how it could be implemented for integrating with some 3-d Party Product "XYZ", which wants to read the Incidents:
- Create a dedicated Person, which will be used for the authentication (e.g. Last Name: XYZ)
- Generate the Web Access Token for the created Person. See more Web Services tokens: Generate API Token
- Add the created Person XYZ to Web Service Operation "fragments.GetList " Audience.
- Grant permissions for reading Incidents for the person XYZ. Create a new Role "XYZ users" and add person XYZ to members. Run action "Set Permissions" for the role "XYZ users" and check the "Read" checkbox for the Configuration Item "Incident"
Services
Objects Data Service
Endpoint: api/data/objects
The Service provides methods for CRUD operations (Create-Read-Update-Delete) for Configuration Items presented in the Schema.
| Operations | Description |
|---|---|
| GET api/data/objects/{ciName}/{objectId} | Retrieves the whole Object with the specified Configuration Item name and Object ID. |
| POST api/data/objects/{ciName} | Creates a new Object of the specified Configuration Item. |
| PUT api/data/objects/{ciName} | Updates the Object of the specified Configuration Item by the Configuration Item name and Object ID. |
| DELETE api/data/objects/{ciName}/{objectId} | Deletes the Object from Database defined by the Configuration Item name and the Object ID. |
Fragments Data Service
Endpoint: api/data/fragments
The Service provides methods for CRUD operations (Create-Read-Update-Delete) for Data Definitions presented in the Schema.
| Operations | Description |
|---|---|
| GET api/data/fragments/{ddname} | Retrieves a list of fragments with a defined list of columns, which match the specified search criteria. |
| GET api/data/fragments/{ddname}/{fragmentid} | Retrieves the whole fragment of the specified Data Definition with defined Id. |
| POST api/data/fragments/{ddname} | Creates a new Data Definition fragment. The operation is required for cases of multi-fragments or optional fragments. |
| PUT api/data/fragments/{ddname} | Updates the specified Data Definition fragment. |
| DELETE api/data/fragments/{ddname}/{objectid:guid} | Deletes the fragment from Database defined by the Data Definition name and the object ID. The operation is required for cases of multi-fragments or optional fragments. |
| Retrieves a list of fragment's relations with a defined list of columns which match the specified search criteria. | |
|
POST api/data/fragments/{ddname}/{fragmentid}/{relationname}/{relationfragmentid} |
Adds relation to the fragment defined by Data Definition name, fragment ID and Relation name. |
|
DELETE api/data/fragments/{ddname}/{fragmentid}/{relationname}/{relationfragmentid} |
Deletes the fragment relation from the Database defined by the Data Definition name and the object ID. |
Benefits
Key benefits of the Generic Data Service include:
Security
Authentication and authorization mechanisms with multi-level permissions management allow access to the shared data assets only to the trusted sourced. Although such approach restricts access at the same time it allows keeping track of the caller's identity and prevents data misuse by the unauthorized sources. Thus it is possible to assure that the company-sensitive data cannot be leaked or corrupted.
Service uniformity
Generic Data Services provide access to a multifarious amount of data by means of a limited number of generic endpoints.
Stability of tried & trusted service
Generic Data Services are standardized and remain intact throughout the life cycle of an API. Besides stability, all users are provided with up-to-date data from a single and authoritative source of information by means of a unified way to access, search and modify the Matrix42 platform’s underlying sources.
Data scalability & operations flexibility
Due to its consistent architecture implemented Generic Data Services offer the greatest possible degree of data structure scalability for further development and operations. This implies that generic data services allow to operate not only with the existing data structure, modify, delete or add new records, but easily customize and extend the existing data structure. Moreover, the newly introduced and modified data structures can be instantly accessed and operated immediately right after their creation.
Feature use cases
As the Generic Data Service provides raw data via API there are no limits on how these services can be used and integrated. Adapt data according to your varying needs, for instance:
Access shared data assets
Generic data services provide an easy-to-use mechanism for accessing and operating data and data structures of the Matrix42 platform.
Seamless integration
The generic approach offers an easy way to integrate with any 3-rd party application as it is not bound to any specific programming language or platform, would it be mobile, web or even wearable.
Bring more added value
Automate routine processes and bring the usage of other internal systems or applications of your company to a new level:
- Send data from the in-house software programs directly to the Matrix42 platform;
- Pull data from Matrix42 platform to the in-house software systems: for internally used reporting systems, CRMs, internal databases, etc.