API Reference Overview #

Introduction #

Zypr is organized around HTTP REST using JSON as the wire format for requests and responses. It uses standard HTTP response codes, authentication, and verbs.

The base URL for Zypr is:  

https://api.zypr.app

Authentication #

Zypr uses an API key in the request header to authenticate requests; a password is not required. Use 'x-api-key' as the key when adding the header line to your request.

All API requests must be made over HTTPS. Authentication failure, or calls made over HTTP, will return 401 response code.

A unique API key is issued for each user. Your API key permits certain permissions as a trial user or as a named user within your organization. Please keep your key secure. Do not share your API key in publicly accessible areas.

Rate Limiting #

To promote the stability of Zypr, the endpoint for requesting a simulation (i.e., create a scenario) is rate limited. Sending too many requests to the endpoint will result in a 429 response code.

Dates, Times and Time Zone Offset #

Date and time values that Zypr creates and processes internally are in Coordinated Universal Time (UTC), with time based on the 24-hour clock system. When defining a JSON-based Pool Resource Model, your date and time values should generally conform to ISO 8601. To specify any date property in your local time, add a UTC time zone offset. Zypr will accept the following string formats:

Formats that explicitly designate time offset from UTC (e.g., your local time).

• YYYY-MM-DD hh:mm:ss±h   — or ending (ss ±h)
• YYYY-MM-DD hh:mm:ss±hh

Formats that explicitly designate time as UTC.

• YYYY-MM-DD hh:mm:ssZ
• YYYY-MM-DDThh:mm:ssZ

Formats that omit UTC time offset will be inferred as UTC with no time zone offset.

• YYYY-MM-DD
• YYYY-MM-DD hh:mm:ss
• YYYY-MM-DDThh:mm:ss

Zypr outputs date and time values in UTC using the format of YYYY-MM-DDThh:mm:ssZ.

Numerics #

Where an object's property is defined as an integer, an integral number is expected. Where an object's property is defined as a numeric, an integer or decimal number is expected. Expressing a number as a string in a culture-specific format will fail validation unless the string value resolves as culture invariant.

Performance Ratings #

The performance rating of a unit of hardware is represented as a scalar value and referred to by Zypr as Performance or Perf. You assign performance scalar values to hardware based on whatever methodology works best for your organization. Scalar values provide a means to compare the relative performance among many hardware units (e.g., a server).

Zypr requires a performance scalar value to be an integer with at least 3 digits. The lowest acceptable value is 100. This requirement is to minimize rounding issues that arise in piecewise operations.

Identifiers #

Correlation Id #

Every API request is issued a correlation identifier. You can find this value in the response header key of x-correlation-id. If you have a problem, referring to this value will be helpful to Zypr staff towards resolving an issue. #

Scenario Id #

A scenario identifier is created for each create a scenario request. The Scenario Id is a property of the response object. You will need the Scenario Id to query the status of a running simulation and retrieve a simulation result. #

Resource Pool Concepts #

A resource pool (i.e., a pool) is a collection of hardware and software resources that may host one or many workloads and are indifferent to which resources in the pool they consume.

To a workload owner, pool resources are fungible. To a pool operator, workloads may be assigned resources anywhere within the pool and changes in load may be balanced across the pool with minimal friction.

Zypr is indifferent to the specific technologies a pool employs to achieve these characteristics (e.g., OS clustering, virtual machines, containers, etc.).

Resource requirements, mix, utilization, and total cost are managed on a per pool basis.

Start a Simulation #

Zypr defines an instance of a simulation as a scenario. A request to start a simulation is therefore a request to create a new scenario.

To create a new scenario, Zypr requires a model that describes a resource pool (e.g., a service, cluster, etc.). Zypr refers to that model as a Pool Resource Model (PRM). PRM is a JSON object to describe the characteristics of a pool along with rules, events, and constraints that govern how pool composition and resource consumption evolve on a forward-looking basis. It includes the following child objects:

• Settings
• Simulation Rules
• Evolution Rules
• Valuation Rules
• Power Consumption Terms
• Facility Consumption Terms
• New Server Configuration
• Software Resources
• Server Inventory
• Jump Events
• Constraints  

Receive a Simulation Result #

The output of every simulation request is a unique Scenario object. The Scenario object contains information necessary to monitor a running simulation through to its completion and is identified by a scenario Id. The content of the Scenario object depends upon the state of the simulation when the Scenario object is received.

A simulation may terminate in different states (see next sections). The desired end-state of a simulation is a Scenario object that includes a completed ResourceRequirementsForecast object, which includes the following Stats and time-series objects:

• Financial Stats
• Financial Summary Item
• Hardware Stats
• Hardware Summary Item
• Hardware Detail Item
• Software Stats
• Software Summary Item
• Software Detail Item
• Facility Stats
• Facility Summary Item
• Facility Detail Item

Simulation States #

A simulation is a long-running task that advances through the following states:

• Received request
• Start request initiated
• Model validation succeeded
• Request added to simulator queue
• Simulator verified start
• Simulator is executing
• Simulator completed

These states are reported in the SimulationStates array of the Scenario response object. The most recent state, or final status, is reported on the StatusNbr and StatusDescription properties of the Scenario object.

A unique Scenario object is first created as the response object of the create a scenario endpoint. If your model passes validation, the response Scenario object will only include simulation states up to "Request added to simulator queue". After this state, the simulation request is handed off to a a different environment that is dedicated to hosting Zypr's simulator (see Simulator Host Environment). You are not able to directly interact with this environment.

To monitor the state of a simulation, or fetch a completed simulation, use the Scenario record endpoint using the scenario Id. If the simulation is still executing, the Scenario object will include additional progress information in the Progress array object. If the simulation has completed, the response Scenario object will contain additional state information (e.g., a resources forecast, errors, no solution found, etc.).

Simulation Errors #

Errors are reported in the Errors array in the Scenario object. Errors, or unsuccessful simulations (see No Feasible Solution Found and Resources Forecast Validation Check sections), that arise from the Pool Resource Model have status numbers in the 1x range. Errors corresponding to the execution of the simulator have status numbers in the 2x range. Host environment-based errors have status numbers in the 5x-6x range.

When requesting a simulation, the submitted Pool Resource Model is validated before the request is added to the simulator's processing queue. If a model fails validation, a Scenario object is immediately returned having a 422 HTTP code. Too many simulation requests will also produce a pre-simulation processing error and return the 429 HTTP code.

All other errors, or unsuccessful simulations, may be identified from the Scenario response object of the Scenario record endpoint. The HTTP response from this endpoint has no relationship to the state of a simulation; an HTTP 200 response means the request to retrieve the scenario succeeded.

No Feasible Solution Found #

A simulation request may return a Scenario object indicating no feasible solution was found. That may occur when one or more Constraints are include in a model definition but are too limiting. Additional information for this type of error is found in the No Solutions Graphs array.

Alternatively, Zypr may simply not able to find any solution. This is rare and is handled as an internal error by Zypr and reported in the Errors array of the Scenario object.

Resources Forecast Validation Check #

All simulations that return a populated ResourceRequirementsForecast object, within the Scenario response object, are checked to confirm state data is within acceptable tolerances from one time-interval to the next. Validations performed include:

• Start and end times (in years)
• Scalar demand
• Scalar capacity
• Server utilization rates
• Required license vs actual position
• Server transactions correspond to server inventory balances
• Rack unit server quantities correspond to server transaction quantities and balances
• Hardware unit interval quantities sum to cumulative or maximum totals
• Financial interval values sum to cumulative totals

The ValidationPassed property is located in the Scenario response object. If this property returns false, the ValidationResults object identifies what failed to pass, actual quantity, and the tolerance factor used. It is up to you decide if the value that falls outside the tolerance factor Zypr used is meaningful to your results.

Simulator Host Environment #

Zypr's simulator runs in a dedicated host environment solely for executing simulations. This is a shared environment for executing simulation requests from multiple clients.

If your organization prefers to run its simulations in a dedicated host, that configuration is also available.