Is that a good practice to provide a aggregation API in a Rest or a normal WebAPI Design?

Question

I have provide such REST API for getting base user info and user's space info.

/v1/users/{user_id}/profile, which will return such a JSON:

```json {

"id":123, "name":"foo", "sex":0, "email":"foo@gmail.com", } ```

/v1/users/{user_id}/space , which also return a JSON:

```json { "sum_space":100, "used_space":20, }

Now if a client (e.g. web page, a 3rd application) have a view which need to show part of user info(e.g "name", "sex") and part of user space info (e.g "sum_space") in a same time, Do I need to provide a new aggregation API such like /v1/users/{user_id}?

And if I provide such a aggregation API, should it return all attributes of User and Space? if I did so, the return value will include some unused values, which will increase the bandwidth of network. But if this API just return what client need, what should I do if a new client requirement come(e.g just get a user's name and user's used_space)?

If I don't provide any aggregation API, all the client must call N times for getting N kinds of resource. if there are a requirement for filter search(e.g getting user list which sum space > 100), the client could only do this serially.

I am very confuse about those, is that any guideline to follow?

score 1 · Answer 1 · answered Aug 29 '16 at 14:30

Provide base data at /users/{id}. Allow clients to include the optional query parameter ?expand=profile, space. If they pick both, they get a detailed response with data from all three endpoints. If they only pick, say, profile, then they get the base data and the profile data.

If you need them to be able to restrict to exactly the properties they need, you can also support an ?include query parameter, that might look like GET /users/{id}?include=id,lastModifiedDate,profile.name&expand=profile and might get back something like

{
    "id": 25,
    "lastModifiedDate": 0,
    "profile": {
        "name": "Bob Smith"
    }
}

You can mess around with the URI structure above as you like. Maybe you prefer GET /users/{id}?include=id,lastModifiedDate&expand=profile[name]. The point is that you can use query parameters to define the type of information you get back.

Another choice, if you're using vendor-specific MIME types, would be to use a different mime type for different shapes of response. One type might return the profile and space, while another would return just one or the other, when a request is made to GET /users/{id}. That's a particularly blunt instrument though, and it doesn't sound appropriate for your needs.

Is that a good practice to provide a aggregation API in a Rest or a normal WebAPI Design?

1 Answers1