-
Notifications
You must be signed in to change notification settings - Fork 519
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Intake API responses: Body and content type investigation/thoughts #6
Comments
I agree that we should include more descriptive error messages. This will be particularly useful for signaling that the apm-server internal queue is full or that it can't contact the upstream Elasticsearch (or kafka) etc. These will be 5xx responses. In the apm-server, we'd include the error JSON payload if the agent sent an I like
When looking at the payload you might not see that the response code is not a 2xx (and as you wrote, curl by default doesn't display the status code), so the |
@watson can we agree on the above? |
@roncohen sounds good to me 👍 And good point with using What do you want to do with 404 and 405 responses? Should they have a body at all? If so, I imagine that body should follow the |
This makes a simple check on the Accept header to determine if the client will understand a JSON response and then sends back: {"error": "Cannot compare apples to oranges"} It will fall back to plain text messages if the Accept header is not present or does not indicate JSON compatibility. Closes #6.
I just did a little test to see what type of data the server responds with in case of an issue. I tried to trigger all types of errors below 5xx (didn't have a proper way of generating a 5xx response).
All the responses I saw used the correct HTTP status code. That's good. But all responses used
text/plain
and notapplication/json
as I would have expected.For an HTTP API that's primarily consumed programmatically, we should prioritise responding with a format that's easily parsable by a computer. Below is how our respones look today.
Invalid URL (result: 404)
Invalid HTTP method (result: 405)
Invalid
Content-Type
(result: 400)Data validation error (result: 400)
Notice how the 400 respones repeats the message twice but uses a slightly different wording, e.g. both "Data Validation error" and "Problem validating JSON document against schema". I suggest we just use the former.
Personally I always respond with an empty body in for instance 404 and 405 responses - as no extra info is needed. But since curl by default doesn't display the status code, there is a certain merit in displaying some text to a human for debugging purposes. So we can choose to continue responding with a body if it helps - but I'm also fine with just leaving the body empty in that case. We could also let this depend on the
Accept
header (curl will setAccept: */*
by default, but our agents could setAccept: application/json
)The JSON Schema validation errors seem to contain line breaks and other special formatting that I expect comes directly from the JSON validator. It would be nice if this could be cleaned up in some way.
We had previously talked about always responding with JSON, e.g:
What do you think about implementing this? Would love to hear pros/cons 😃
The text was updated successfully, but these errors were encountered: