[API] Documentation: Error object

[STiAT]

Hi there,

I'd like to ask if it's possible to get more documentation on the error object dynatrace can return if you ... do something semantically wrong.

I found the following documentation, which leaves a lot to imagination (or to be true: I couldn't find any docs on the error structures possibly returned):

https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-response-codes

Dynatrace (especially v2 API) tends to return error structures with messages and why it failed (constraints not met etc.). They seem to be pretty "standard" error json structures, but it would be nice if it was actually in the docs and not having to try to find out with try-and-error what kind of json models dynatrace returns on semantic errors.

Background:

I'm building API implementaitons in Golang and Python and currently try to wrap the Golang lib up to make it more complete and open source it (it's public at https://codeberg.org/STiAT/go-dynatrace).

Still some work to do to make it cleaner since it was highly driven by my demands and not the "bare" API standard you provide which should be the attempt for the library, but this will be done soon (TM). It probably will end up with a github mirror once I deem it ready enough (which includes: It needs proper documentation).

[AntonioSousa]

@STiAT,

In the API documentation, most of the calls have documentation for Response codes, and what might go wrong.

I understand that sometimes there are some "cryptic" replies, when we don't put in data as it is required. I believe you are referring to these cases. Do you have some examples, before turning this into a "Product Idea"?

[STiAT]

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entities-list

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entity

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/events-v2/post-event

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/topology-and-smartscape/hosts-a...

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/topology-and-smartscape/process...

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entity-type

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/problems-v2/comments/get-all

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/problems-v2/comments/put-commen...

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/problems-v2/comments/get-commen...

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/events-v2/get-events

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/events-v2/get-event-types

The question rather is: In which cases is it in the documentation? I found 3 cases where I randomly clicked through the docs, whereas above didn't have documentation. I didn't go through [every] API for now, but I can do that if you want to and give you a listing which include docs and which do not.

Most responses only have documentation for the "successful" case, but not the error case, which makes it a try-and-error for every call what could possibly occur.

It's of course my personal opinion, but for me an API documentation should include both, response documentation in case of successful calls, and for failed calls.

[STiAT]

Hi,

I've made a "small" list based on my API list to be implemented (517 as a number). It documents what I think about the APIs and what is missing:

https://docs.google.com/spreadsheets/d/1gKbjyRtOToMqBLiRS64Ahz-KmgybHn_ZPIzYNxIlAyA/edit?usp=sharing

What you can see throughout is the inconsistent documentation, especially on return codes, but as well on GET requests, which I had most issues with.

Hardly any GET request specifies any return. Some of them just return empty structures, some do fail since some filters fail (especially v2 APIs) which I guess are ErrorEnvelopes, but it's not even mentioned in the docs.

Some of where return codes are missing will very likely default on the default values, but you sometimes do have documentation on it - sometimes you don't. At least mention in the docs they do default on errors to the defaults (as you sometimes did, but if you do LINK it and do not just write default, or even better: Just do the documentation where the error will occur). Mostly you do not have documentation on it at all, I think in two cases you mentioned "default", and in some cases (22) you did have documentation on it.

You clearly have no clean error strategy throughout the whole API (or at least not in the API documentation, you may still handle similar errors similarly just the docs being not up to it), which is fine with supplying two versions, but make sure it's consistent and has consistent and complete documentations for the appropriate version of the APIs.

I may have missed a few, and there may be some mistakes in there, but it's pretty much as complete and good as I could get it tonight.

I even found some funny artifacts as:

https://www.dynatrace.com/support/help/dynatrace-api/configuration-api/extensions-api/get-global-con...

General issues with the docs: Why do I require an id to update if I want to get a global configuration?

Where you clearly have a copy/paste error on the docs :D.

Eamples:

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entity

I am pretty sure I do get a ErrorEnvelope if the fields I specify are not correct.

https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entities-list

I am pretty sure I do get a ErrorEnvelope if the entitySelector fails.

And there are a lot more of those. I just had a glance at it for now and went through it pretty fast, there may be more feedback coming. But it boils down to about 263 where I think the docs are insufficient in the current state.

I did not yet get into the wrongly stated required/optional stuff, and there is a lot of this too, but that will require a deeper and more throughout investigation and tests for that, this will probably have to be done API by API and will take some time.

Don't get me wrong - this is an opinion, and my opinion, but I think feedback to be considered ;-).

[AntonioSousa]

@STiAT,

Yesterday; I had clicked on the first API on the list, and it did show some error code:

But given your examples, it seems that most of them really don't have additional information for errors.

BTW, when I referred to "some examples", I was referring to the error structures/strings that you are encountering. If you can provide them, they might be a starting point to get more details on them.

[STiAT]

As another reply, what is really annoying in the docs is when you only specify "object" as a type and not a specific object and how it's built up... as in the Settings API at List Schemas:

enums

object

A list of definitions of enum properties.

This would be probably EnumType, but there are a lot of occurrences of this in your API docs.

Also, the Precondition object in the settings API is recursive, as well as I do not see the need for Precondition Precondition and Preconditions []Precondition. Recursive declarations are always a very bad idea in that space, since it needs to be nullable in this case, which is a "guess" if you do not have a specification if fields are required or not.

A lot of languages do not allow recursive declarations. You can often work around that using pointers. If you're going that route, we'd need object definition which fields are actually required and optional through ALL APIs, not just by-use-case, so we know which ones are nullable and which ones are not.