Hi, in my job we are trying to modify an API endpoint (
/resources) to make special queries to it. A
resource has a location (long/lat) and we want to make queries based on that location. We want to support mainly two different filters:
- Filter by lat/long (already done):
GET /resources?lat=0&long=0returns a list of
resourcewith that location.
- Filter by a
polygon(currently designing): a polygon is a very long sequence of points and we want to return those
resources that are included in that polygon.
Both filters return an array of
resources but with different representations.
The new filter has three main problems:
- Due to the length of the polygon (represented by and array or vertices) we cannot use a query parameter.
- This filter is quite time consuming in our backend, so we need to implement it in an
- Both endpoints return different representations of each resource (both return an array of
resourcebut in a different format).
Solution first problem
We are going to use the
body of the request instead of a query parameter. So we call the endpoint like:
"vertices": [ ... very long list of lat/long values ... ]
We think this solution is the only available.
Solution second problem
We are going to use jobs. By that I mean the following:
GET /resources -> returns a job_id -> once it's finished the frontend gets notified -> frontend calls a new endpoint GET /resources?job_id=<job_id>
We see some drawbacks in this design:
- To differentiate the type of filter, we need to check the parameters: if
zoomare included, then it's the first filter. If the body is not empty and contains a list of
vertices(the polygon), then is the second one. We think this is a bad approach and it's not "very restful".
Solution thrid problem
As stated in the third problem, we are returning different representations but we do not specify that anywhere. To fix that, we have thought of using the
Content Type header and create our own types, like
application/json;<our_type>, but we are not sure about this solution either.
How do you think we should solve these problems? Can you give us some guidelines or resources to try to improve the solution?