REST API reference documents - Output clarification

[purestaketdb]

In the documents here - https://developer.algorand.org/docs/reference/rest-apis/algod/ - all endpoints state that they have an output Content-Type in the format application/json.

Above the statement concerning the output, is typically a table of different response codes, example -

`HTTP Code	Description	Schema
200	TransactionIDResponse contains a transaction information	transactionID
400	Bad Request	string
401	Invalid API Token	No Content
500	Internal Error	string
default	Unknown Error	No Content`

Confusion arises between the schema defined in the table, particularly for an error, and the expected Content-Type of the message and the different SDK's error handling.

For example, the PureStake API had the result of a 400 bad transaction returned as application/json content type although the actual output is not JSON but a string TransactionPool.Remember: txn dead: round 5395354 outside of 5153790--5154790.

This can cause parsing errors in the JS SDK library when it expects a JSON object. We switched it to produce 'text/plain' but are not certain if that was correct.

Ideally everything would return as JSON and the SDKs could properly parse out errors like the above. If not feasible, some clarification in the documentation about the expected Content-Type for the different response codes.

[purestaketdb]

Following up on this, using the sandbox I constructed a local curl command with a bad transactions and did get a 'text/plain' response. Moving forward with the assumption then that all errors specified as 'string' return as 'text/plain'.

`root@7ff87f1bb76a:/opt/algorand/node# curl -v -X POST --data-binary @./400_test_2.tx -H "X-Algo-API-Token: $(cat ./data/algod.token)" -H "Content-Type: application/x-binary" http://127.0.0.1:4001/v1/transactions
Note: Unnecessary use of -X or --request, POST is already inferred.

• Trying 127.0.0.1...
• TCP_NODELAY set
• Connected to 127.0.0.1 (127.0.0.1) port 4001 (#0)

POST /v1/transactions HTTP/1.1
Host: 127.0.0.1:4001
User-Agent: curl/7.58.0
Accept: /
X-Algo-API-Token: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Content-Type: application/x-binary
Content-Length: 258

• upload completely sent off: 258 out of 258 bytes
  < HTTP/1.1 400 Bad Request
  < Access-Control-Allow-Headers: X-Algo-API-Token, Content-Type
  < Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
  < Access-Control-Allow-Origin: *
  < Date: Thu, 12 Mar 2020 14:34:15 GMT
  < Content-Length: 77
  < Content-Type: text/plain; charset=utf-8
  <
• Connection #0 to host 127.0.0.1 left intact
  TransactionPool.Remember: txn dead: round 5455525 outside of 5153790--5154790root@7ff87f1bb76a:/opt/algorand/node# `

[ejbaran]

This inconsistent behavior is expected to be fixed as part of an upcoming release. We will comment here with more information as it becomes available.