Skip to main content

API (Platform)

Introduction​

Enov8’s REST-API allows you to automatically Create, Update & Read information. Which in turn allows you to integrate other platforms and automation scripts, for example CICD scripts to capture “version”, or test automation scripts to capture “health”.

Currently the following three types of requests are supported.

  1. POST (Create)
  2. PUT (Update)
  3. GET (Read)

REST-API Prerequisites​

The following will be required before using the enov8 REST-API

  • The API URL of your enov8 instance e.g. https://company.enov8.com/ecosystem/api/[CLASSNAME]

    Here the [CLASSNAME] will be replaced with the name of the class on which action has to be performed.

  • An ”API KEY” comprising of the following parameters

    • app_id (Application ID)

    • app_key (Application Key)

    • user_id

Generating an API Key​

To create an API Key within the Enov8 platform, users must have System Admin access. If you do not possess this level of access, please contact your Enov8 system administrator for assistance. The following steps outline the process for generating an API Key:

Steps for System Admin Users:

  • Log In: Sign in to the Enov8 platform using your System Admin credentials.

  • Navigate: Proceed to Configuration Management > System Administration > API Management within the platform.

  • Create API Key: Select the "Add API Key" option to initiate the creation of a new API Key.

    Alt text

    Alt text

  • Enter Application ID: Provide your Application ID and click on "Generate Random Key" to create your Application Key.

  • Set Permissions: Choose the necessary permissions for the API Key, which may include Read, Create, and/or Update options.

  • Save: Click on "Save" to finalize the creation of the API Key.

  • Confirmation: Upon successful creation, you will see a message indicating that the API Key has been created successfully.

    Note: It is crucial to securely store your Application ID and API Key details for future reference. 

Class Definitions​

The Permission & Class Definition module within the Enov8 platform is a vital tool for obtaining detailed information about the properties of an API call and understanding user permissions. This module offers insights into the specific attributes and permissions associated with different classes within the ecosystem.

Accessing the Permission & Class Definition Module:

  • Login: Access the Enov8 platform by entering your login credentials.

  • Help Icon: Once logged in, locate and click on the help icon situated on the top bar of the platform's interface.

  • Navigate: By clicking the help icon, you will open the Permission & Class Definition section.

  • Class/Property Definition Widget: Within this section, find the Class/Property Definition widget.

  • Select Class: Use the widget to select the class you are interested in. Once selected, you will be able to view the property definitions for that particular class.

    Alt text

REST API End Points​

The following is the list of API End Points available in ecosystem

Class NameAPI End Point
Environment{ecosystem api url}/Environment
System{ecosystem api url}/System
SystemInstance{ecosystem api url}/SystemInstance
SystemComponent{ecosystem api url}/SystemComponent
User{ecosystem api url}/User
LeanSR{ecosystem api url}/LeanSR
EnvEvent{ecosystem api url}/EnvEvent
Group{ecosystem api url}/Group
Runsheet{ecosystem api url}/Runsheet
Task{ecosystem api url}/Task
Tag{ecosystem api url}/Tag
BusinessUnit{ecosystem api url}/BusinessUnit
BusinessTeam{ecosystem api url}/BusinessTeam
BusinessProcess{ecosystem api url}/BusinessProcess
Release{ecosystem api url}/Release
Project{ecosystem api url}/Project
Project<->System{ecosystem api url}/Project<->System
Booking{ecosystem api url}/Booking
Booking<->SystemInstance{ecosystem api url}/Booking<->SystemInstance
Gate{ecosystem api url}/Gate
Activity{ecosystem api url}/Activity
PIR{ecosystem api url}/PIR
TechnicalSpecification{ecosystem api url}/TechnicalSpecification
TestAccount{ecosystem api url}/TestAccount
ITService{ecosystem api url}/ITService
System<->System{ecosystem api url}/System<->System
SystemInstance<->SystemInstance{ecosystem api url}/SystemInstance<->SystemInstance

Read REST API​

To fetch data from a particular class within the ecosystem, you can utilize a GET REST API call. This method allows you to query specific data by defining the class, properties, and conditions within the URL structure.

URL Structure for GET REST API Call

{ecosystem api url}/ClassName&properties=PropertyNames&Conditions

  • {ecosystem api url}: Replace this with the actual URL of your ecosystem API endpoint.
  • ClassName: Specify the class name from which you want to retrieve data.
  • PropertyNames: Define the properties you wish to fetch from the specified class.
  • Conditions: Include any conditions or filters to apply to the data retrieval.

Request Header Configuration

For the REST API call to be authenticated, it's crucial to include specific details in the request header. These details should correspond to the ones generated in the previous steps of setting up your API access. Ensure to include the following parameters in the header of your API request:

  • user-id: The unique identifier for the user, as generated or defined during the setup process.
  • app-id: The application ID that was created when you registered your application or obtained API access.
  • app-key: The application key associated with your app-id, serving as a secret key for authentication.

By including these parameters in the header, you ensure secure and authenticated communication with the ecosystem's API.

Alt text

PropertyNames: This parameter allows you to specify which properties of the class you wish to retrieve. By including specific property names, you can tailor the API response to include only the relevant data you need, making the API call more efficient. For example, if you only need the 'Resource Name' and 'Status' properties from a class, you can specify these in the PropertyNames field.

Conditions: The Conditions field is used to apply specific criteria to your data retrieval. This is akin to adding a filter to your API request, where only data that meets the specified conditions will be returned. For instance, you could use conditions to retrieve data where a 'Status' property equals 'InOperation', thereby narrowing down the results to active items only.

Example

In this specific example, we're querying data from the SystemInstance class. The properties requested are Resource Name and Status. Additionally, we've applied conditions to filter the data: we're only interested in instances where the Status is InOperation and the System is Tallyman.

{ecosystem api url}/SystemInstance?properties=Resource Name,Status&Status=InOperation&System=Tallyman

Sample URL

http://companydemo.enov8.com/ecosystem/api/SystemInstance?properties=Resource Name,Status&Status=InOperation&System=Tallyman

Example Output

Alt text

Create REST API​

To create data for a specific class within the ecosystem, a POST REST API call is utilized. This method allows you to add new entries to a designated class in the ecosystem's database.

URL Structure

{ecosystem api url}/ClassName

HTTP Method

POST

Request Header Configuration

For the REST API call to be authenticated, it's crucial to include specific details in the request header. These details should correspond to the ones generated in the previous steps of setting up your API access. Ensure to include the following parameters in the header of your API request:

  • user-id: The unique identifier for the user, as generated or defined during the setup process.
  • app-id: The application ID that was created when you registered your application or obtained API access.
  • app-key: The application key associated with your app-id, serving as a secret key for authentication.

By including these parameters in the header, you ensure secure and authenticated communication with the ecosystem's API. Alt text

Body When creating data in the ecosystem for a specific class using a POST REST API call, the body of the request plays a crucial role. Here's how to structure the body using JSON format:

JSON Body Structure:

  • The body of the POST request must contain JSON-formatted data, which specifies the properties and their corresponding values for the class you are updating or creating data for.
  • The JSON payload should include each property name followed by its value. It's essential to ensure that all required or mandatory properties for the class are included in the JSON payload to successfully create the data entry.

Example of JSON Payload

{ "propertyName1": "value1", "propertyName2": "value2", }

Replace propertyName1, propertyName2, etc., with the actual property names of the class, and value1, value2, etc., with the respective values you wish to assign.

Referencing Class Definitions:

  • To accurately construct your JSON payload, you should reference the class definition module in the ecosystem. This module provides detailed information about the properties associated with each class, including which properties are mandatory.
  • Understanding the class structure and requirements will guide you in forming a valid JSON payload that the ecosystem API can process effectively.

Sample JSON Payload

Alt text

Example

{ecosystem api url}/EnvEvent

Sample URL

http://companydemo.enov8.com/ecosystem/api/EnvEvent

Sample JSON

{
    "Summary": "Demo Event",
    "Start Timestamp": "01-01-2022 00:00:00",
    "End Timestamp": "15-01-2022 04:00:00",
    "Environment": "ECO-000000004093",
    "SystemInstance": "ECO-000000113980;ECO-000000114181",
    "Type": "EnvDeployment",
    "Status": "Planned",
    "Assigned To": "ECO-000000004225",
    "Organisation": "ECO-000000003945"
}

In this example data is being sent to ecosystem to create an environment event.

Example Output

Alt text

Update REST API​

To modify existing data within a specific class in the ecosystem, a PUT REST API call is employed. This type of API call allows you to update records by specifying the class and the data you wish to change.

URL Structure

{ecosystem api url}/ClassName

HTTP Method

PUT

Request Header Configuration

For the REST API call to be authenticated, it's crucial to include specific details in the request header. These details should correspond to the ones generated in the previous steps of setting up your API access. Ensure to include the following parameters in the header of your API request:

  • user-id: The unique identifier for the user, as generated or defined during the setup process.
  • app-id: The application ID that was created when you registered your application or obtained API access.
  • app-key: The application key associated with your app-id, serving as a secret key for authentication.

By including these parameters in the header, you ensure secure and authenticated communication with the ecosystem's API. Alt text

Body

When updating data in the ecosystem for a specific class using a PUT REST API call, the body of the request is essential. It must be formatted correctly to ensure the data is updated accurately.

JSON Body Structure for Data Update:

  • The body should contain JSON-formatted data specifying the properties to be updated along with their new values. This precise specification allows the ecosystem to identify which values need to be changed.
  • It is crucial to include the "System ID" within the JSON payload. The "System ID" uniquely identifies the object or record that is being updated, ensuring the correct data is modified.

Sample JSON Payload

{
    "System ID":"ECO-000000192052",
    "Status":"Passed"
}

Example

{ecosystem api url}/EnvEvent

Sample URL

http://companydemo.enov8.com/ecosystem/api/EnvEvent

Sample JSON

{
    "System ID":"ECO-000000192052",
    "Status":"Passed"
}

In this example, we are sending data to the ecosystem to update the status of an environment event. The event in question is identified by the System ID "ECO-000000192052". The data transmitted will specify the new status that should be applied to this particular environment event within the ecosystem.

Example Output

Alt text

Custom Update API​

Apart from the standard API calls, the following endpoints allow updating the status of Environment Instances and the version of Microservices. These calls can be integrated with your CI/CD tools to update the Enov8 CMDB.

Environment Instance Version​

This sample can be used to update the version of an environment instance.

End Point

{ecosystem api url}/SystemInstance

HTTP Method

PUT

Sample URL

http://companydemo.enov8.com/ecosystem/api/SystemInstance

Sample JSON Payload

{
 "Resource Name": "Tallyman (PROD)",
 "Version":"10.2"
 
}

In this example, we are sending data to the ecosystem to update the version of an environment instance. Here the environment instance is being identified by using the resource name property instead of using standard property "System ID".

Example Output

Alt text

Environment Instance Status​

This sample can be used to update the status of an environment instance.

End Point

{ecosystem api url}/SystemInstance

HTTP Method

PUT

Sample URL

http://companydemo.enov8.com/ecosystem/api/SystemInstance

Sample JSON Payload

{
 "Resource Name": "Tallyman (PROD)",
 "Status":"UnplannedOutage"
 
}

In this example, we are sending data to the ecosystem to update the status of an environment instance. Here the environment instance is being identified by using the resource name property instead of using standard property "System ID".

Example Output

Alt text

MicroService Version​

This sample can be used to update the version of a micro service for an environment instance.

End Point

{ecosystem api url}/MicroService

HTTP Method

PUT

Sample URL

http://companydemo.enov8.com/ecosystem/api/MicroService

Sample JSON Payload

{
    "MicroService Name": "Web Portal",
    "SystemInstance": "GDW (DEV)",
    "Version": "20.33"
}

In this example, we are sending data to the ecosystem to update the version of a micro service for a particular environment instance. Here the microservice is being identified by environment instance and microservice name instead of using standard property "System ID".

Example Output

Alt text

MicroService Status​

This sample can be used to update the status of a micro service for an environment instance.

End Point

{ecosystem api url}/MicroService

HTTP Method

PUT

Sample URL

http://companydemo.enov8.com/ecosystem/api/MicroService

Sample JSON Payload

{
    "MicroService Name": "Web Portal",
    "SystemInstance": "GDW (DEV)",
    "Status": "UnplannedOutage"
}

In this example, we are sending data to the ecosystem to update the status of a micro service for a particular environment instance. Here the microservice is being identified by environment instance and microservice name instead of using standard property "System ID".

Example Output

Alt text

API Examples (Postman Collection)​

Click here to download the Postman collection with example requests for various Ecosystem REST API scenarios.

note

If you're unsure how to import the collection into Postman, please refer to the Postman documentation for a step-by-step guide on importing collection.