API Migration

The API v1 endpoints are deprecated and existing applications can be migrated to the API v2 endpoints. The API v2 provides similar endpoints to API v1 so that applications can start and stop machines. In addition, the API v2 enables applications to manage machine pools. Please refer to the API v2 documentation to know more about the new features and the exact definitions of each endpoint.

The v2 API also adds or improves the following features:

  • The use of encrypted communication with HTTPS is enforced. If an application tries to use the endpoint over HTTP, it will not be redirected to HTTPS but an error will be returned instead.
  • The API signature is no longer necessary and it is replaced by sending Gurobi headers X-GUROBI-ACCESS-ID and X-GUROBI-SECRET-KEY representing the access ID and the secret key that can be retrieved in the Instant Cloud Manager. This simplifies the client code necessary to call the endpoints while maintaining a secured communication.
  • The API v2 supports multiple simultaneous API keys. This is useful when one needs to replace an API key that is already in use by an application or some users. With this feature, you can generate a new key, update the applications or notify the users, and finally delete the old key when necessary. During this process, you will not incur downtime of the applications or experience user access issues. You can also generate multiple keys for tracking purpose.
  • The API v2 supports global account keys and dedicated license keys. The global account keys can access all the machines and pools related to all licenses of the account. A dedicated license key is allowed to access machines and pools of a given license only. So you can embed or deliver the keys with better access control.
  • In case of errors due to invalid data or an issue detected on the server, a JSON object is always returned. This enables clients to better parse and react to these errors.
  • All v2 endpoints have a version prefix /api/v2 to manage current and future versions.
  • Machine passwords are used to secure communications and administrative commands with the compute servers. With the API v2, machine passwords cannot be set by API anymore but can be accessed and re-generated using the Instant Cloud Manager, in the settings section.

Note that the API v1 key will not work for API v2 endpoints. To use the API v2 endpoints, users will need to access the Instant Cloud Manager and get or generate new keys. Once the applications have been migrated, the API v1 key can be deleted to make sure it won't be used anymore.

The following table gives a more detailed mapping of the endpoints followed by a description of the main changes:

Operation V1 endpoint V2 endpoint Description
GET /api/licenses /api/v2/licenses List licenses
GET /api/machines /api/v2/machines List machines
POST /api/launch /api/v2/launch Launch machines
POST /api/kill /api/v2/terminate Terminate machines

GET /api/v2/licenses

  • In v1, the returned list was only including valid licenses. In v2, all the active licenses are returned with attributes indicating if they are valid (see invalid and invalidSate).

GET /api/v2/machines

  • Machine states have been renamed and extended, the possible values are the following: 'launching', 'pending', 'configuring', 'starting', 'killing', ' shutting down', 'error', ' idle', 'running'. If the application uses the machine state, please update it accordingly.
  • Many more attributes are returned, including latest status providing the idle time, the actual Gurobi version and the actual job limit.
  • Query string is now supported to filter return machine descriptions by one or more machine ids.
  • Note that a new API endpoint has been added to access machines by ID (see api/v2/machines/{id}). Another new endpoint can be used to list distributed workers of a compute server (see api/v2/machines/{id}/distributedWorkers).

POST /api/v2/launch

  • Only the machine IDs are returned instead of the full machine descriptions. If the application needs to access or follow machine state changes, then the use of other endpoints is preferred (see api/v2/machines/{id} or api/v2/machines).

POST /api/v2/terminate

  • Nothing is returned. If the application needs to access or follow machine state changes, then the use of other endpoints is preferred (see api/v2/machines/{id} or api/v2/machines).