I have moved this discussion here, because it seems that having a record of it would be reasonable.
Original question
@richared wrote:
api-courses and api-course-search - Why are these separate API's? Couldn't the request parameters decide what type of answer is returned?
Context
This is a result of a more general design decision, and it applies to some other "API pairs" too:
Courses API and Course Search API
IIAs API and IIA Search API
Outgoing Mobilities API and Outgoing Mobility Search API
This design decision is:
Search APIs return lists of IDs only, based on filter parameters supplied by the client. Servers MUST allow the clients to retrieve a complete list of all the IDs through these APIs.
Retrieval APIs return dictionaries of objects, based on a list of IDs supplied by the client. Servers MAY limit the number of the returned objects in these APIs.
Of course, we can change this decision, if we find a better way to support all the use cases. But first, I'll try to explain why this design decision seems reasonable.
Explanation
These APIs are of course related, but still "separate enough" to be able to draw a line between them (loose coupling). This way, we keep "filtering" and "retrieval" in separate APIs and we are able to implement them separately. E.g. we can implement various complementary search APIs while keeping a single retrieval API (and vice versa, e.g. different formatters for the same search result).
There's one obvious drawback: The client will often need to make two requests instead of just one (one to retrieve the IDs, and one to retrieve the actual objects).
However, joining these APIs would have drawbacks of its own too. Note, that Search APIs may return a huge number of results. That's why they are returning IDs (and possibly "last modified" dates) only. Adding a limit on the number of returned items seems a bad idea, because we want the clients to be able to use Search APIs for initial and periodical replication (they will often need to start such replication with fetching a complete list of IDs, e.g. in order to determine which entities have been recently deleted). We could add a new offset or page_number parameter, but this would introduce further complexity and problems (e.g. related to read consistency, when the result changes between subsequent requests).
Other options?
We probably could implement a "merged" and more complex API for each of these "API pairs", which would address all of these problems... But I think it would be much safer to have a set of really simple APIs instead.
In other words, despite this slight drawback, I still think we should stick with this design (separate "search" and "retrieval" APIs).
wrygiel
commented
8 years ago
I have moved this discussion here, because it seems that having a record of it would be reasonable.
Original question
@richared wrote:
This is a result of a more general design decision, and it applies to some other "API pairs" too:
This design decision is:
Of course, we can change this decision, if we find a better way to support all the use cases. But first, I'll try to explain why this design decision seems reasonable.
Explanation
These APIs are of course related, but still "separate enough" to be able to draw a line between them (loose coupling). This way, we keep "filtering" and "retrieval" in separate APIs and we are able to implement them separately. E.g. we can implement various complementary search APIs while keeping a single retrieval API (and vice versa, e.g. different formatters for the same search result).
There's one obvious drawback: The client will often need to make two requests instead of just one (one to retrieve the IDs, and one to retrieve the actual objects).
However, joining these APIs would have drawbacks of its own too. Note, that Search APIs may return a huge number of results. That's why they are returning IDs (and possibly "last modified" dates) only. Adding a limit on the number of returned items seems a bad idea, because we want the clients to be able to use Search APIs for initial and periodical replication (they will often need to start such replication with fetching a complete list of IDs, e.g. in order to determine which entities have been recently deleted). We could add a new
offsetorpage_numberparameter, but this would introduce further complexity and problems (e.g. related to read consistency, when the result changes between subsequent requests).Other options?
We probably could implement a "merged" and more complex API for each of these "API pairs", which would address all of these problems... But I think it would be much safer to have a set of really simple APIs instead.
In other words, despite this slight drawback, I still think we should stick with this design (separate "search" and "retrieval" APIs).