Skip to content

API Endpoints Reference

Overview

Zypr endpoints provide a means to simulate how a pool's resource composition evolves for a preferred period of time.

A user may be a person or a third-party application. A user must be registered to execute a simulation. A User object describes a user.

A pool is a collection of servers organized to provide a particular service and composed with a common software stack. The service may be a large, single workload or host many different workloads using container or virtual machine technologies. The scope of a pool is defined by technical and business constraints. A PoolResourcesModel object describes the initial state of a pool.

An executed simulation produces a scenario, which is described by the Scenario object and includes the ResourcesForecast object. This object is a collection of resource forecasts that describe the future state of pool over time.

User Management

VerbURLPurpose
POST/usersCreate new trial user
PUT/users/{Activation Code}/register-userConfirm registration and receive API key
PUT/users/{Email Address}/request-new-api-keyRequest new API key
PUT/users/{Authorization Code}/create-new-api-keyAuthorize create new API key
GET/users/{Email Address}/infoUser record
DELETE/users/{Email Address}/Delete user

 

Simulation Management (scenarios)

VerbURLPurpose
POST/scenariosCreate a scenario
GET/scenarios/{Scenario Id}/scenarioGet scenario
GET/scenarios/{Email Address}/{quantity}Get recent scenario ids. Quantity sets maximum number of ids to return.
DELETE/scenarios/{Scenario Id}Delete scenario

 

Create new trial user

Registration as a trial user can be accomplished without any credentials, and is a two step process. The first step requires identifying yourself, your organization, and your organization provided email address. An email is sent to this address with an activation code. The activation is used in the second step to confirm your email address is valid, complete your registration, and issue you an API Key.

Request object

curl {BASE URL}/users
    -X POST
    -H "Content-Type: application/json"
    -d '{
        "FirstName": "Sally",
        "LastName": "Doe",
        "Email": "sallydoe@company.com",
        "Organization": "my company name"
       }' 

Response object

json
  {
    "Message": "Email sent to sallydoe@company.com
                that contains activation code."
  }

INFO

The activation code you receive is valid for 24 hours.

 

Confirm user email and receive API key

Request URL

curl {BASE URL}/users/{Activation Code}/register-user
    -X PUT
    -H "Content-Type: application/json"
   

Response object

json
  {
    "UserName": "sallydoe@company.com",
    "Role": "TrialUser",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

INFO

Please note the expiration date of your API key. Please reach out to us if you need to additional time.

 

Request new API key

Replacing an existing API key is a two-step process. First, submit a request that contains the email address you used to register with Zypr. A change authorization code will be sent to your email address. Use the authorization code to create a new API key.

Request URL

curl {BASE URL}/users/{My Email Address}/request-new-api-key
    -X PUT
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

Response object

json
  Valid request
  {
    "Message": "Email sent to sallydoe@company.com that contains change authorization code."
  }

INFO

The change authorization code is valid for 10 minutes.

 

Authorize create new API key

Request URL

curl {BASE URL}/users/{Authorization Code}/create-new-api-key
    -X PUT
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

Response object

json
  {
    "FirstName": "Sally",
    "LastName": "Doe",
    "Role": "TrialUser",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

INFO

Your new API key will retain the same expiration date as the original key.

 

Create a scenario

To generate a scenario, add a PoolResourcesModel object to the request body. The PoolResourcesModel object is large, so the code block below contains an empty request object. Refer to the Pool Resources Model object reference for a complete description of a valid json object.

Request object

curl {BASE URL}/scenarios
    -X POST
    -H "Content-Type: application/json" 
    -H "x-api-key: your_api_key"  
    -d '{                                         
          "PoolResourcesModel": {                   
            "Settings": {},
            "SimulationRules": {},
            "EvolutionRules": {},
            "ValuationRules": {},
            "NewServerConfiguration": {},
            "PowerConsumptionTerms": {},
            "FacilityConsumptionTerms": {},
            "SoftwareResource":{
                "SoftwareStackRegistry":[],
                "SoftwareInventoryTerms":[]
            },
            "ServerInventory":[],
            "JumpEvents":[],
          }
        }'

TIP

Because the PoolResourcesModel is large, it may prove helpful to use an online, visual tool to define your object and confirm it is valid JSON.

Response object

json
  {
    "Id":"a51940fb-f72c-4aab-ab99-210c0d38e925",
    "StatusNbr": 7,
    "StatusDescription": "Simulator completed",
    "Settings": {
      "ScenarioName": "My Scenario Name",
      "DataValidationCascadeMode": "Stop",
      "ModelEffectiveDate": "1/7/2022",
      "ModelStartDate": "1/7/2022",
      "ScenarioCreateDate": "2/1/2022",
      "EmailResults": true,
      "CultureInfoISOCode": "EN"
    },
    "JobStates": [..],
    "Progress": {},
    "ResourcesForecast": {..},
    "NoSolutionGraphs": null,
    "Errors": null
  }

The response is a Scenario object. The Settings object included in the submitted PoolResourcesModel object has been modified by Zypr to include the highlighted properties in the code block above.

  • ScenarioId property that uniquely represents the request to create a new scenario.
  • ModelStartDate property that represents the starting date of the all time-series in the ResourcesForecast object.
  • ScenarioRunDate property that represents the date when the scenario was created.

If a valid ModelEffectiveDate property was not included in the request Settings object, or it's left blank or null, then the ModelStartDate property will have the same date as the ScenarioRunDate property. If a valid date was included in the request Settings object for the ModelEffectiveDate property, then the ModelStartDate property will have the same date as the ModelEffectiveDate property. Zypr never modifies the ModelEffectiveDate property.

INFO

Each request to create a scenario will be assigned a unique scenario id.

 

User record

Request URL

curl {BASE URL}/users/{Email Address}/info
    -X PUT
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

Response object

json
  {
    "UserName" : "sallydoe@company.com",
    "Status" : "Active", 
    "Role" : "TrialUser", 
    "FirstName" : "Sally", 
    "LastName" : "Doe",
    "Organization" : "Company",
    "ApiExpirationDate" : "date",
    "DaysRemaining" : 60
  }

 

Delete user

Request URL

curl {BASE URL}/users/{Email Address}
    -X DELETE
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

INFO

Only an authorized user is permitted to delete a user account.

Response object

json
  {
    "Message": "User sallydoe@company.com was successfully deleted"
  }

 

Get scenario

Request URL

curl {BASE URL}/scenarios/{Scenario Id}/scenario
    -X PUT
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

TIP

Use this endpoint to retrieve the state of a in-process scenario create request (job state) or a completed scenario.

Response object

json
  {
    "Id":"a51940fb-f72c-4aab-ab99-210c0d38e925",
    "StatusNbr": 6,
    "StatusDescription": "Simulator executing",
    "Settings": {},
    "JobStates": [..],
    "Progress": {
       "Started" : true,
       "Completed" : false,
       "PercentComplete" : 78,
       "TransactionCount" : 17824,
       "SequenceCount" : 1286
    },
    "ResourcesForecast": {},
    "NoSolutionGraphs": null,
    "Errors": null
  }

INFO

Scenario response object is an example of a simulation that is still executing.

 

Get recent scenario ids

Request URL

curl {BASE URL}/scenarios/{Email Address}/{Quantity}
    -X GET
    -H "Content-Type: application/json"
    -H "x-api-key: your_existing_api_key"
    

Response object

json
{
  "Scenarios" : [
    {
      "Id" : "yyyyyyyyyyyyyyyyyyy",
      "CreateDate": "date",
      "Status": "Simulator reports error",
      "FirstError": "A validation error message example" 
    },
    {
      "Id" : "zzzzzzzzzzzzzzzzzzz",
      "CreateDate": "date",
      "Status": "Simulator completed",
      "FirstError": null 
    },
  ]
}

Ravello Analytics, LLC