Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[SecuritySolution][Timeline] Refactor timeline HTTP API (elastic#200633)
## Summary
The timeline API endpoints are currently implemented from a mix of HTTP
and GraphQL practices. Since GraphQL has been removed for a long time
now, we should make sure the endpoints conform to HTTP best practices.
This will allow us to simplify the API- and client-logic. Further,
third-parties accessing these APIs will have an easier time integrating.
### Usage of HTTP status codes
Depending on the error, the API endpoints currently return a `200` with
`{ code: 404, message: '(...)' }` or an actual HTTP error response with
e.g. `403` and the message in the body. The practice of returning 200s
with embedded error codes comes from GraphQL, where error codes are
always embedded.
Example of a current HTTP response of a failed timeline request:
```
HTTP status: 200
HTTP body:
{
"error_code": 409,
"messsage": "there was a conflict"
}
```
Going forward, all endpoints should return proper error codes and embed
the error messages in the response body.
```
HTTP status: 409
HTTP body:
{
"messsage": "there was a conflict"
}
```
### Removal of `{}` responses
Some timeline endpoints might return empty objects in case they were not
able to resolve/retrieve some SOs. The empty object implies a `404`
response. This creates complications on the client that now have to
provide extra logic for how to interpret empty objects.
Example of a current request of one of the endpoints that allows empty
responses.
```
HTTP status: 200
{}
```
The absence of an object, on some of the listed endpoints, indicates a
404 or the top-level or embedded saved object.
Going forward, the endpoints should not return empty objects and instead
return the proper HTTP error code (e.g. `404`) or a success code.
```
HTTP status: 404
```
### No more nested bodies
Another relic of the GraphQL time is the nesting of request bodies like
this:
```
HTTP status: 200
HTTP body:
{
"data": {
"persistTimeline": {
(actual timeline object)
}
}
}
```
Combined with sometimes returning empty objects and potentially
returning a status code in the body, makes it overly complicated for
clients to reason about the response.
Going forward, the actual object(s) should be returned as a top-level
JSON object, omitting `data.persistX`.
```
HTTP status: 200
HTTP body:
{
(actual timeline object)
}
```
### Checklist
- [x]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [x] This was checked for breaking HTTP API changes, and any breaking
changes have been approved by the breaking-change committee. The
`release_note:breaking` label should be applied in these situations.
---------
Co-authored-by: kibanamachine <[email protected]>
Co-authored-by: Elastic Machine <[email protected]>- Loading branch information
1 parent
6029106
commit 4dd9f7f