Armrest gem guideline


#1

Armrest gem is a gem we develop to bridge the gap between ruby usage and Azure Rest API calls. It is still in its early stage of development.

I am doing some refactoring to the armrest gem. Here are some thoughts I have as a general guideline.

  1. Manage a simple one-to-one mapping between ruby calls and Rest API calls. It is up to the caller to make multiple calls to combine results.
    For example, VirtualMachineService#list should not include vm’s power state which requires another API call.
    This design is beneficiary for performance without undesired extra API calls, also easy understood for users who have knowledge of the raw Rest API.

  2. Options are passed to API without modification (insert/delete/reorg). Options are often used in create method.
    Callers with the knowledge of the raw Rest API can easily construct the options hash. They don’t need to understand another set of rules to provide options to armrest gem.

  3. Return should normally be either a model object, or nil. Throw exceptions otherwise. Avoid directly expose the raw Rest response string.

  4. Argument list ordering is in the opposite direction of the Rest endpoint,
    typically subresource, resource, group, for example,
    get(subnet, network, group)
    get(operation, deployment, group)

Your comments? Anything else? Please.