Feature request: Account limit information

[philippfreyer]

Feature Request

I want to use the Python HCloud API to automate server creation and management for my project - basically, we want to start servers to run our application whenever a customer needs an instance of the application. These servers are long-lived and will not be shut down any time soon. Thus we will run into the server count limit quite soon. I understand that this limit is per account and can be increased, however, it would be very helpful to be able to monitor this limit automatically and react to the server count getting close to the limit. In addition, I would like to test beforehand if the new server would still fit into the limit or if I need to postpone server creation until a server is available or the limit has been increased.

I understand that the limits are not per project while the API is. Thus I see two different solutions for this:

1. (Preferred solution): Report on Limits anyways using either limit and usage attributes on the particular objects (e.g. Server) or an additional Limit object (I would prefer that since it bundles all information in one place). It needs to be understood that the usage metrics associated with the limits may change due to changes in other projects, thus error handling is still needed. Monitoring would be working well, though.

2. Dry runs - the possibility to do a dry run on what you wanted to do. Flags are added to the requests to basically try what you want to do as a dry-run and simulate the result, checking the API Limits, ... . This would still not be a guaranteed success for e.g. server creation if the dry-run succeeds and the server creation is triggered afterward (for example if another server has been created in parallel and the server limit is now used up). But it would help for testing if what the script wants to do works and is at least sufficiently safe to do.

In any case required

I do not see any information in the cloud API documentation on what happens if I try to create a server using the API and the API limits are used up. Which errors do I have to catch and how can I differentiate between a server limit issue and e.g. an availability or connection issue?

Teachability, Documentation, Adoption, Migration Strategy

While the documentation in general either needs a section on limits and what happens when they are reached (I would especially expect that documented on e.g. the ServersClient.create() call), adding limit information would mostly add a new section to the API documentation and does not necessarily need any migration unless error reporting will change the behavior of certain methods (e.g. if the ServersClient.create() method now could throw an exception). Here, the philosophical question of throwing exceptions vs. adjusting flags in the returned object is relevant. The first would be explicit but would be breaking code, the second would still need to be looked out for but is most likely less invasive. Personally, I prefer solutions that let me choose between either option using an optional keyword argument to turn exceptions either on or off.