search

PagerDuty / pdpyras

Low-level PagerDuty REST/Events API client for Python
MIT License
129 stars 29 forks source link

Add square brackets to array type parameters if the user forgets to do so #38

Closed Deconstrained closed 2 years ago

Deconstrained commented 3 years ago

This is a very common beginner error when dealing with the REST API.

Filtering parameters of array type, known as "set filters", must end with [].

It would be really nice to bake this into the client.

Deconstrained commented 2 years ago

The trick will be writing this in a way that is agnostic to the features of the API to avoid "making an API for the API" and sticking with the design philosophy that has kept this library stable and low-maintenance. The best option is modifying a parameter if its value is a list. I think it's safe to say that if this assumption is broken in the future by newer APIs, then the problem would not be with the client but with the API because that in itself makes it an antipattern that runs contrary to our own public API documentation (regarding set filters).

Deconstrained commented 2 years ago

Possible footgun / surprise: a user absentmindedly passes a list to a parameter and the API says "invalid parameter name" or the like for the param whose name was updated. This only would apply to a parameter that doesn't support being a set filter, and recognizing this specifically as the failure (to provide a more helpful error message) would require baking in knowledge of the API's validation rules, or parsing of the error message in order to rewrite it, neither of which are ideal.

Deconstrained commented 2 years ago

Fixed in #70 (v4.4.0)