General REST-API issues (Bugs)

[micha91]

In this discussion, we will collect issues, we have when using the Polarion REST-API. We only want to collect things here, which are in our opinion bugs, and no feature/refactoring requests.

[micha91]

For all response descriptions there is a collective description of how errors are structured:

"400" : {
  "description" : "Bad Request"
},
"401" : {
  "description" : "Unauthorized"
},
"403" : {
  "description" : "Forbidden"
},
"404" : {
  "description" : "Not Found"
},
"406" : {
  "description" : "Not Acceptable"
},
"500" : {
  "description" : "Internal Server Error"
},
"503" : {
  "description" : "Service Unavailable"
},
"4XX-5XX" : {
  "description" : "Error responses have the following structure:",
  "content" : {
    "application/json" : {
      "schema" : {
        "$ref" : "#/components/schemas/errors"
      }
    }
  }
}

According to the openapi 3 specification, you can only define error ranges using codes like 4xx, but it seems to be not allowed to combine multiple ranges or define ranges like this 4xx-5xx. In addition, every specific definition of an error code overwrites the range based one. For that reason, we would love to see the error content in all described error codes as well. Otherwise an auto generated API-Client does not parse the error message.

[micha91]

If we send an attachment to the server, we have to send MultiForm content containing a resource description and the files itself. The resource is send in json as described in the API-Documentation. But the content type for the resource object must be set to text/plain and it will crash with an exception, if we set it to application/json, which would be the expected content type for a json object. In addition, the error response is not really helpful, as it tells us to read the logs on the server, where we found a long stack trace with this as the resulting exception, which could also have been sent back as error response.

java.lang.IllegalStateException: Media type is not text/plain.

[micha91]

We sometimes receive Errors, which contain source with the value null. This is unexpected, as we would expect to either not receive source or to receive it filled with a proper value as described in the specification.