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 #

Simulation Management (scenarios) #

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 #

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

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 #

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

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 #

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

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 #

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

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":[],
          }
        }'

Response object #

  {
    "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.

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 #

  {
    "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"
    

Response object #

  {
    "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"
    

Response object #

  {
    "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
  }

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 #

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