About OvalEdge APIs

Application Programming Interfaces (APIs) provide a standardized set of rules and protocols that enable software systems to communicate and exchange data. In OvalEdge, APIs handle request and response interactions, working as a bridge between OvalEdge and external systems. They support key functions such as:

• Retrieving object metadata

• Updating metadata attributes

• Creating or deleting objects

• Managing user access and roles

• Configuring connections to external systems

• Creating domains, terms, and tags

• Establishing data lineage

• Performing impact analysis

A complete set of APIs is available to support user management, metadata tasks, governance settings, and integration across the application.

API Access and Usage

API access is available to users with administrative roles (OE_Admin or Role Admin) or to users who have been explicitly granted access. OvalEdge provides configurable system settings to control API access, usage, and response behavior. These settings enable administrators to:

• Define role-based API permissions

• Restrict or allow access based on system-level rules

• Manage the structure and size of API responses

For additional details, refer to the OvalEdge API System Settings.

OvalEdge uses JWT (JSON Web Token) authorization to access Swagger APIs. A JWT is a standardized method for securely transmitting information between parties in JSON format. It is commonly used for authentication and authorization in web applications.

The following steps outline the process for authorizing Swagger APIs using a JWT:

1. Launch the OvalEdge application.

2. From the left panel, navigate to Advanced Tools and select Application APIs.

   
3. The Swagger interface opens, displaying all available API services.

   
4. Click Authorize in the top-right corner. The Available Authorizations pop-up window appears.

   

Generating the JWT Token

1. Navigate to the OvalEdge Home Page and click the User Profile icon in the top-right corner.

2. Select My Profile, then click the grid (9-dots) icon.

   
3. Select Download User API Credentials. A pop-up window appears.

   
4. Click Download User API Credentials. The credentials file is downloaded to the system's default download location (e.g., /My Computer/Downloads).

5. Open the downloaded file and copy the credentials.

   
6. Return to Advanced Tools > Application APIs.

7. On the Swagger page, expand the "User API" section to view the available endpoints.

   
8. Locate the following endpoint: POST /api/user/token/generate

   

9. Click Try it Out.

   
10. In the request body:

    1. Delete the placeholder text.

    2. Paste the copied API credentials.

    3. Click Execute.

    
11. A JWT token is generated and displayed in the response body.

    

Authorizing Swagger API Access

1. Click Authorize in the top-right corner of the Swagger page.

   
2. In the authorization pop-up:

   • In the Value field, enter: jwt <token> (replace <token> with the generated token).

     

   • Click Authorize. Upon successful authentication, users can execute authorized API calls. All request and response bodies use the JSON format, structured according to the system’s design specifications.

Available API Methods

OvalEdge APIs provide standard methods for creating, fetching, modifying, and deleting metadata. The following are listed:

API Method	Definition	Use Case
GET	Retrieve metadata from a specified object or entity.	Fetching metadata from the application without modifying it. Example: Fetching user information
POST	Submit metadata to a designated object or create a new object.	Adding a new object to the application or metadata to an object. Example: Creating a tag
PUT	Update or replace an existing object or create a new one if it doesn't exist.	Modifying an existing object or creating a new one. Example: Updating License Type
PATCH	Apply partial modifications to an object.	Making partial updates to an existing object without replacing the entire content. Example: Reactivating a deactivated user
DELETE	Request the removal of an object.	Deleting an object or data from the application. Example: Deleting a term

Types of APIs

The following API groups are available, each containing a set of endpoints designed to perform specific operations within the application.

API Group	Description
AI Functions API	Provides endpoints to access AI-based functionalities such as automated metadata description.
Asset Management API	Provides endpoints to add and delete assets, retrieve asset details by ID, and check the virus scan status of assets.
Axiomatics Payload API	Enables updating process flags and retrieving individual or all Axiomatics payloads.
Business Glossary API	Supports assigning terms to objects, and adding, modifying, searching, and retrieving terms. Also enables domain-wise term retrieval, business glossary export, and deletion of associated objects.
Business App Management API	Enables the management of business applications within the system, including the creation, updating, association, and retrieval of application-related metadata and configurations.
Column API	Allows saving table columns, adding custom fields, updating descriptions, deactivating columns, and retrieving column and wiki details.
Connector API	Enables updating connector credentials, saving new connectors, managing crawler/profile rules, and retrieving connector information and parameters.
Custom Fields API	Supports adding custom fields to objects and retrieving defined custom fields.
Data Quality Rule API	Offers functionality to manage data quality rules, including updating status, scheduling, running rules, associating objects, and deleting rules and schedules.
Diagnostic API	Enables retrieval of OASIS properties, infrastructure metrics, and deployment health status.
Endorsement API	Allows saving or updating endorsement ratings and retrieving average endorsement scores.
Entity Relationship API	Supports retrieving and managing relationships between data entities, enabling the visualization and analysis of how objects, such as tables, columns, reports, or terms, are connected.
File API	Supports saving/uploading files via URLs, retrieving wiki and file details, obtaining file statistics, and profiling files.
File Column API	Enables saving, retrieving, and managing file column details.
File Folder API	Provides functionality to create, retrieve, and delete file folders, including folder-specific details.
Generic API	Includes the certifyObject endpoint, used to certify Data Catalog objects similar to the Certification feature.
Global Domain API	Retrieves business glossary domains, classifications, categorized objects, columns, and category details.
Governance Roles API	Allows updating of governance roles assigned within the system.
Impact Analysis API	Supports submission of custom impact analysis batches, retrieving impacted objects, and fetching analysis details by batch or object.
Job Status API	Provides endpoints to execute advanced jobs, update job statuses, and retrieve detailed job information, including step and overall status.
Lineage API	Enables adding and deleting lineage data, retrieving lineage graphs (by object or column, with or without names), and managing lineage records by ID or type.
Message API	Allows posting collaboration messages on objects, handling authorization, retrieving missing file alerts, and accessing specific object messages.
Object API	Supports the creation and updating of objects via API.
Object Attribute API	Enables saving and retrieving object attributes from the Data Catalog.
Object Group API	Provides endpoints to retrieve API groups and the objects associated with a specific group.
PowerBI Reporting Supportive APIs	Offers supplementary APIs specifically for Power BI integration, including fetching metadata, lineage, and usage details to support advanced reporting and analytics.
Project API	Allows creating projects, retrieving project lists and details, managing associated objects, and deleting projects.
Query API	Enables managing saved queries, including updating, executing, parsing queries, and retrieving results or associated tables.
Report API	Supports adding, retrieving, and deleting reports, as well as accessing report descriptions from the Data Catalog.
Report Column API	Provides functionality to add, retrieve, and delete report columns, and to access their descriptions from the Data Catalog.
Report Group API	Enables managing report groups by adding, retrieving, and deleting them, including fetching details by group ID.
Schema API	Facilitates schema-related operations, including description updates, schema crawling, deactivation, and fetching connector-specific schemas.
Search API	Enables retrieving search results for various objects such as tables, reports, columns, terms, files, and stories.
Security API	Manages roles and privileges, including user-role mappings, role creation/modification, and privilege retrieval or deletion.
Service Desk API	Allows creating service desk tickets and retrieving ticket templates, including general and active templates.
Story API	Supports the addition and updating of stories in the Data Stories module.
Table API	Enables saving, updating, deactivating, and reactivating tables. Also supports metadata comparison, profile saving, and retrieving schema-specific tables.
Tag API	Provides endpoints for tag management, including adding, retrieving, updating, deleting, and associating/disassociating tags with objects.
User API	Supports user management tasks, including creating, updating, reactivating, and deleting users, as well as managing licenses, roles, and API tokens.
Wiki API	Allows retrieving description details and types of objects stored in the Data Catalog.

Example:

OvalEdge provides a range of APIs designed to handle various actions in the application. Each API has unique methods that allow users to perform specific tasks.

1. /api/user (GET): Retrieve detailed information about an OvalEdge user based on their User ID.

2. /api/user/update (POST): Update and save changes to an existing user's details.

3. /api/user/license (PUT): Assign or update the license information for a specific user.

4. /api/user/reactivate (PATCH): Restore user accounts to active status after deactivation.

5. /api/user/delete (DELETE): Permanently remove or mark users as inactive in the OvalEdge system.

HTTP Status Codes / Error Responses

An HTTP status code is a server response to the request made by the browser. The following status codes apply to all HTTP operations in this API service:

Status Code	Message	Description
200	Successful	Indicates that the request was successful
400	Bad Request	Indicates that the server could not understand the request due to invalid syntax
401	Unauthorized	Indicates that the client must authenticate itself before accessing the requested resource
403	Forbidden	Indicates that the server has understood the request, but the client does not have permission to access the requested resource
404	Not Found	Indicates that the requested resource could not be found
500	Internal Server Error	Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request

OvalEdge APIs System Settings

OvalEdge provides configurable system settings to control API access, usage, and response behavior. These settings allow administrators to define role-based API permissions, restrict or allow access based on system-level rules, and manage the structure and size of API responses.

Key	Value	Description
ovaledge.api.role	Accepted Values: One or more role names Default Value: OE_ADMIN	Defines the roles authorized to execute OvalEdge APIs. Note: Select one or more roles from the drop-down list to grant API execution privileges.
is.apirole.mandatory	Accepted Values: True, False Default Value: False	Determines whether role-based API access control is enforced based on ovaledge.api.role and oe.apirole.read. Note: Set to True to restrict API access to the specified roles. Set to False to allow all users to access APIs regardless of their role.
oe.apirole.read	Accepted Values: One or more role names Default Value: OE_ADMIN	Grants read-only API access (GET method) to the specified roles. Note: Use this setting to define roles permitted to retrieve data via APIs without write access.
include.catalog.apiresponse	Accepted Values: OVALEDGE_APP, other values	Specifies whether catalog names should be included in API responses. Note: Set to OVALEDGE_APP to enable catalog name inclusion in the response body.
api.summary.paging.limit	Accepted Values: Numeric value	Controls the number of API attributes displayed on the summary page. Usage Notes: Set a numeric limit to optimize response size and improve API performance.