Pretty difficult to use

Start with the SyntheticsApi entry points named in the report—list_tests, get_api_test, patch_test, and update_api_test—and reproduce the version 2.19.0 behavior, including the validation error. Also inspect repr() behavior for Monitor and its type field. The issue needs to be narrowed into actionable bugs with separate expected behavior and tests before implementation can be considered done.

Describe the bug
This API is just not great.

I needed to write a script to just find & replace one Slack channel that was our notifications on monitors to another. This was … difficult.

I'm going to summarize a number of usability issues here; filing a bug for each would be onerous.

• SyntheticsApi includes both a patch_test, and an update_api_test. I have absolutely no idea what the difference between "patch" and "update" is, and the docs don't tell me.

• AFAICT, SyntheticsApi.patch_test (as documented here) is a lie? I have the latest version of the library, and AFAICT, that, and the associated types, just don't exist.

• If you SyntheticsApi.list_tests, you get, essentially, a list of SyntheticsTestDetails. (It is wrapped by a pointless wrapper object, but that's whatever.) However, update_api_test requires a SyntheticsAPITest, so you can't pass the result to it!

• If you call get_api_test, however, you'll get the right type: a SyntheticsAPITest! But attempting to then call update_api_test with that results in a runtime error:

  HTTP response body: {'errors': ["Additional properties are not allowed ('modified_at', 'creator', 'monitor_id', 'created_at' were unexpected)"]}
  

  I attempted a number of things to attempt to remove those properties form the object, but none of which worked. … the entire point of a type system is that if you function declares itself to take a Foo, then you should be able to pass it instances of Foo. If you can't, you have foo instances that aren't really Foo.

• #1794, which was severe enough that I have split it out to a separate bug.

• authn issues appear to return 403, which sent me down the wrong paths for a bit.

• Many of the types in the library, when repr'd, do not emit faithful reprs. For example, if you repr a monitor, you'll get,

  …
   'type': 'synthetics alert'}
  

  This led to me writing bugs such as,

  monitor['type'] == 'synthetics alert'
  

  Which is False (!) for the above. That's because the value for 'type' there is not truly a string, it's a MonitorType. The repr here is just … lying.

  Python's has built-in support for enumerations in the form of the enum module, and it won't do stuff like this that will leave one pulling out one's hair mid debugging session.

  (Even the outer type there appears to be a dict when repr()'d … but its not.)

Environment and Versions (please complete the following information):
A clear and precise description of your setup:

• version for this project in use: 2.19.0 (latest, as of the time of writing)

Additional context
As you might be able to tell from the above, most of my frustration was around the synthetics portion. I was actually successful at updating non-synthetics monitors — except for running into errors with monitors that were actually synthetics (another Liskov substitutability violation, really), and then attempting to update those with SyntheticsApi. I eventually gave up, and just did it by hand … we don't have that many synthetics.