API design for sub array of nested resources

Question

I'm currently working on an API for an education app. There's a teacher resource and each teacher has a list of subjects that they teach. Currently, the GET teacher endpoint looks like this:

{
    "first_name" : "Mister"
    "last_name" : "Teacher"
    "subjects" : [
        {
             "name" : "English",
             "icons" : "/english-icon.png"
             "id" : 1
        },
        {
             "name" : "Math",
             "icons" : "/math-icon.png"
             "id" : 2
        }   
    ]
}

However, to me it doesn't make sense send the entire subject object when creating and updating the subjects, so the POST and PUT student endpoints accept parameters in the following form:

{
    "first_name" : "Mister"
    "last_name" : "Teacher"
    "subject_ids": [1,2]
}

The inconsistency seems ugly, and it forces the client application to modify the format of an object before sending it to the server. Is there a more elegant solution?

user1907906 · Accepted Answer · 2015-05-20 05:04:03Z

1

First, you should include a link to each subject, not only the ID. This allows the client to navigate to a subject without having to build the URL from a pattern (which?) and the ID.

Second, your approach is fine if you think in think in representations. Both JSON structures are representations of the same resource. But they use different formats. In HTTP client and server would tell each other which format they send, request, or understand by using Content Negotiation.

Collectives™ on Stack Overflow

API design for sub array of nested resources

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related