Advice on API design

[rajzru]

I want to understand the best practices that we need to consider while designing API responses.

Problem Statement

Let's assume I have an endpoint /v1/projects/all which return the list of projects and its response look something like this

{
    "projects": [{
        "id": "001",
        "name": "test nw UPM member",
        "isPublic": false,
        "isShared": false,
    }, {
        "id": "002",
        "name": "move test",
        "isPublic": false,
        "isShared": true,
    }]
}

Notice the isShared flag indicates if the project is shared with other users. If it is

true - It means the project is shared with another user
false - It means the project is not shared with another user

Now I have another API that only gives me the list of shared projects

The endpoint looks something like this /v1/projects/shared-by-me The response of that looks like below

{
    "projects": [{
        "id": "002",
        "name": "move test",
        "isPublic": false,
    }]
}

Note: I do not pass isShared flag here since the endpoint itself indicates that projects are shared by me meaning isShared will be always true in that case.

Question

What according to best practices should the response be like? Should I include the isShared property in /v1/projects/shared-by-me or it's ok to not include that?

Client Side Implementation

Assume client-side has a common react component that renders the details based on this response. so If I don't pass isShared it is recommended for the Client-side to add it manually and add conditional rendering?

[chasdev]

I would try to keep the ‘projects’ resource representation consistent (i.e., with ‘isShared’) and not impose any additional requirements on a client to understand that additional properties are needed and that they must be defaulted to some value if missing. I would also change the URLs (/projects/all and /projects/shared-by-me) to use a query parameter instead (e.g., /projects?filter=all and /projects?filter=shared-by-me). The current URLs depict two separate nested resources (‘all’ and ‘shared-by-me’) under a ‘projects’ resource, and I believe you instead want a single resource and simply need to query it differently. Anyway, hope this helps, good luck.