Appearance
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
Verb | URL | Purpose |
---|---|---|
POST | /users | Create new trial user |
PUT | /users/{Activation Code}/register-user | Confirm registration and receive API key |
PUT | /users/{Email Address}/request-new-api-key | Request new API key |
PUT | /users/{Authorization Code}/create-new-api-key | Authorize create new API key |
GET | /users/{Email Address}/info | User record |
DELETE | /users/{Email Address}/ | Delete user |
Simulation Management (scenarios)
Verb | URL | Purpose |
---|---|---|
POST | /scenarios | Create a scenario |
GET | /scenarios/{Scenario Id}/scenario | Get 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
},
]
}