REST API Overview

Overview

Enov8’s EcoSystem 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”.

Ecosystem API (aka EcoAPI) currently supports 3 types of requests:

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

Interaction with Ecosystem requires a basic understanding of the data structure. i.e. What classes you want to create/update/get the objects. e.g. If you wish to add a new application in the SIT environment, then you should be interacting with the SystemInstance class. If you want to add a new WebServer then you should be interacting with the SystemComponent class e.g.

https://company.enov8.com/ecosystem/api/SystemInstance/
https://company.enov8.com/ecosystem/api/SystemComponent/

An overview of the Test Environment Management and how the core data-structure hangs together can be found here.

 

Getting Started

What you will require before using the EcoSystem API:

  • The URL of your EcoSystem instance e.g. https://company.enov8.com/ecosystem/
  • An API Application ID & Key (refer below setting up access for your application)
  • Existing EcoSystem login (User ID)

Setup API Access for an Application

  1. Login to EcoSystem as a System Admin.
    Tip: You need to be a System Admin to do this.
  2. Navigate to the Configuration Management module from the left menu, expand System Administration and click on API Management.
    Alternatively, simply type ‘API’ into the search bar in the side menu.
  3. Click on the Add API Key button.
  4. Enter the details for the New API Key. The Application ID and Application Key are mandatory. This can be thought of as the username and password for the API access

    Click the Save button.

  5. You can edit the Application ID or Key inline if you need to update it later.

Parameters

Parameters with examples

user_id
Your user ID that you use to log into ecosystem

user1

app_id
Application ID is the ID of your organisation’s API setup (as explained above). This is set up in the EcoAPI section of EcoSystem by a System Admin.

MY_EXTERNAL_APP

app_key
Application Key is your Organisation’s private licence key.

kw9ayen1gm90qu2vxl4q1rn

EcoSystem API URL
API URL is the URL of your ecosystem instance with “/api/” at the end.

https://company.enov8.com/ecosystem/api/

Properties
The JSON response properties you wish to see displayed in the order written. Used for GET – Read requests.

 
User ID,Contact Name,Job Title,User Email ID

Property Conditions

The greater than or equal to/less than or equal to conditions are only used for comparing date values.

--EQUAL TO--
==
--NOT EQUAL TO--
!=
--LESS THAN OR EQUAL TO--
lt=
--GREATER THAN OR EQUAL TO--
gt=

 Class Name
This is the name of the class you would like to update/read/create. The below shows a get request to the User class which would return all users in the system.

https://company.enov8.com/ecosystem/api/User?

Mandatory Fields

To find out what the mandatory fields are for a particular class, select the question mark (?) icon from the top right tool bar and select API Class Definition

All mandatory fields need to provided in the JSON body for POST requests when creating new objects.

From here you simply select the class you wish to interact with, and it will display the fields and whether they are mandatory or optional.

Typically, when updating objects, you must specify the System ID of that object that you wish to update. However, some objects can be updated by referencing their Resource Name if they have this field. Currently the following classes can be updated via their Resource Name: Environment, System, SystemInstance, SystemComponent 

API URL Structure

{ecosystem api url}/{class name}?user_id={user id}&app_id={app id}&app_key={app key}

Example:

https://company.enov8.com/ecosystem/api/User?user_id=user1&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn

When reading information using the GET method, you can specify the properties and the order you want them to be displayed:

{ecosystem api url}/{class name}?user_id={user id}&app_id={app id}&app_key={app key}&Properties={class properties}&{property conditions}

Example below will return a response containing the User Name and User ID of all users that have a role of ‘Environment Manager’

 https://company.enov8.com/ecosystem/api/user?user_id=user1&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn&Properties=User Name,User ID&User Role=Environment Manager

You can add additional filters by adding the ‘&’ symbol to the end of the URL and specifying the property value and its conditions.

Example follows:

&User Name=John Smith&User ID=JohnSmith1

Working examples are shown below.

Examples

Users

GET /User? - Retrieving a list of users with roles as 'environment manager'

Display all Users with the properties & order specified (User ID, Contact Name, Job Title, User Role) and the condition where the User Role must be ‘Environment Manager’.

{ecosystem api url}/User?user_id={user id}&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn&properties=User ID,Contact Name,Job Title,User Role&User Role=Environment Manager

Response


[
 {
   "User ID": "demo",
   "Contact Name": "John Appleased",
   "Job Title": "Environment Manager",
   "User Role": "Environment Manager"
 },
 {
   "User ID": "demo2",
   "Contact Name": "John Smith",
   "Job Title": "Environment Manager",
   "User Role": "Environment Manager"
 }
]

POST /User? - Creating a user

Creating a new user.

Request URL

{ecosystem api url}/User?user_id={user id}&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn

Body

 
{
 "User ID":"JohnSmith123",
 "Contact Name":"John Smith",
 "Job Title":"Solution Architect",
 "User Email ID":"testing123@test.com",
 "User Role":"Environment Manager",
 "User Status":"ActiveUser",
 "Local View":"False",
 "Login Type":"EcoLogin",
 "Password":"password123",
 "Preferred Comms Method":"Email",
 "User Organisations":"ECO-000000003945",
 "Organisation":"ECO-000000003945"
}

Response


{
    "success": true,
    "total_attempted": 1,
    "total_created": 1,
    "result": [
        {
            "success": true,
            "System ID": "ECO-000000192590"
        }
    ],
    "value passed": [
        {
            "User ID": "JohnSmith123",
            "Contact Name": "John Smith",
            "Job Title": "Solution Architect",
            "User Email ID": "testing123@test.com",
            "User Role": "Environment Manager",
            "User Status": "ActiveUser",
            "Local View": "False",
            "Login Type": "EcoLogin",
            "Password": "password123",
            "Preferred Comms Method": "Email",
            "User Organisations": "ECO-000000003945",
            "Organisation": "ECO-000000003945"
        }
    ]
}

PUT /User? - Updating a user

Updating a user’s Contact Name

Tip: You need to use the System ID from the POST response when creating the USER.

HTTP URL

{ecosystem api url}/User?user_id={user id}&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn
 
{
    "success": true,
    "total_attempted": 1,
    "total_updated": 1,
    "result": [
        {
            "success": true,
            "System ID": "ECO-000000192590"
        }
    ],
    "value passed": [
        {
            "System ID": "ECO-000000192590",
            "Contact Name": "John Smith 2.0"
        }
    ]
}

Response


[
 "ROW 0: [OBJ_SUCCESSFUL] Object ECO-000000139191 updated successfully.RELATIONSHIPS : Total EcoRelationship Object Attempted : 0. Total EcoRelationship Object Inserted:0."
]

System Instances

GET /SystemInstance? - Retrieving a list of System Instances that are 'InOperation'

Display all System Instances that are ‘InOperation’ with the following properties & order specified:

  • Resource Name
  • Status
  • System
  • Environment
{ecosystem api url}/systeminstance?user_id=test123&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn&properties=Resource Name,Status,System,Environment&Status=InOperation

Response


[
 {
   "Resource Name": "Tallyman (PROD)",
   "Status": "InOperation",
   "System": "Tallyman",
   "Environment": "PROD Env"
 },
 {
   "Resource Name": "SAP (PROD)",
   "Status": "InOperation",
   "System": "SAP",
   "Environment": "PROD Env"
 }
]

POST /SystemInstance? - Creating a System Instance

Creating a new System Instance.

HTTP URL

{ecosystem api url}/systeminstance?user_id=test123&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn

Body

 
{ 
 "Resource Name":"API Test System Instance",
 "Status":"InOperation",
 "Resilience Maturity":"Weak",
 "Instance Group":"False",
 "Exclusive Lease Cost":"500",
 "Shared Lease Cost":"250",
 "Assigned To":"ECO-000000101968",
 "System":"ECO-000000013633",
 "Environment":"ECO-000000004168",
 "Organisation":"ECO-000000003945"
}

Response


[
 "ROW 0: [OBJ_SUCCESSFUL] Object ECO-000000158324 created successfully.RELATIONSHIPS : Total EcoRelationship Object Attempted : 8. Total EcoRelationship Object Inserted:8. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158325 OBJECT_NAME: ECO-000000158324 - ECO-000000001596. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158326 OBJECT_NAME: ECO-000000158324 - ECO-000000104597. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158327 OBJECT_NAME: ECO-000000158324 - ECO-000000013633 ; REVERSE OBJECT_ID: 158328 OBJECT_NAME: ECO-000000013633 - ECO-000000158324. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158329 OBJECT_NAME: ECO-000000158324 - ECO-000000004168 ; REVERSE OBJECT_ID: 158330 OBJECT_NAME: ECO-000000004168 - ECO-000000158324. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158331 OBJECT_NAME: ECO-000000158324 - ECO-000000101968. [REL_SUCCESSFUL] Object relationship OBJECT_ID: 158332 OBJECT_NAME: ECO-000000158324 - ECO-000000003945."
]

PUT /SystemInstance? - Updating a System Instance

Updating a System Instance’s Resource Name.

HTTP URL

{ecosystem api url}/systeminstance?user_id=test123&app_id=MY_EXTERNAL_APP&app_key=kw9ayen1gm90qu2vxl4q1rn

Body

 
{
 "System ID":"ECO-000000152508",
 "Resource Name":"GDW (SIT) 2.0"
}

Response


[
 "ROW 0: [OBJ_SUCCESSFUL] Object ECO-000000152508 updated successfully.RELATIONSHIPS : Total EcoRelationship Object Attempted : 0. Total EcoRelationship Object Inserted:0."
]

Updated on February 11, 2019

Was this article helpful?

Related Articles