0

I have a question in regards to designing relationships in REST API's. Imagine I have a relationship like in this diagram

diagram

Now, should I show the relationship in the team endpoint like this?

/v1/teams/:id

{
    id: "66e08a2b-2495-4edc-a528-ef00a3f908f1",
    name: "Sales",
    description: "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce tellus odio, dapibus id fermentum quis, suscipit id erat".
    members: [
        {
            id: "a31604c6-2289-4a0b-9127-7219abf4f494",
            name: "John Doe",
            role: "manager"
        },
        {
            id: "fa3c68f4-2008-4bd3-8280-8ae8c4c40a26",
            name: "James Smitt",
            role: "member"
        },
        {
            id: "946d2c3d-415c-4461-850d-892385a65f86",
            firstName: "Jane Doe",
            role: "member"
        }
    ]
}

And an employee endpoint like this:

/v1/employees/:id

{
    id: "a31604c6-2289-4a0b-9127-7219abf4f494",
    name: "John Doe",
    teams: [
        {
            id: "66e08a2b-2495-4edc-a528-ef00a3f908f1",
            name: "Sales",
            role: "manager"
        },
        {
            id: "66e08a2b-2495-4edc-a528-ef00a3f908f1",
            name: "Account management",
            role: "member"
        },

    ]
}

OR should I have a separate endpoint for teammembers?

/v1/teams/:id/members

[
    {
        id: "a31604c6-2289-4a0b-9127-7219abf4f494",
        name: "John Doe",
        role: "manager"
    },
    {
        id: "fa3c68f4-2008-4bd3-8280-8ae8c4c40a26",
        name: "James Smitt",
        role: "member"
    },
    {
        id: "946d2c3d-415c-4461-850d-892385a65f86",
        firstName: "Jane Doe",
        role: "member"
    }
]

And, if I use the separate should I still include the teams and members properties in the employee and team endpoints?

0

Like all things, that is dependent on your requirements. Both options are valid and reasonable on their own. You haven't provided any detail that would suggest one option over the other.

To help with the decision, here are some things to think about:

  • If you are the only consumer of the information, then code to what is most efficient for your needs.
  • If you have external consumers of the information, then code to the interface description.
  • More data takes more time to gather and serialize, sometimes you don't need all of it.
  • Separating data that changes often from data that is mostly static helps when you add caching
  • Each endpoint is more coding and testing required for your application.

There's a lot of reasons why you would want to have the members as part of your JSON object for a team, and a lot of reasons why you might want to separate it out. That said, you could do both--if you had a need to do both.

Bottom line: Decide what your Minimum Viable Product (MVP) is, and evolve from there.

| improve this answer | |
0

should I show the relationship in the team endpoint like this?

There is no particular reason that your resource model should mirror your data model.

The question you are asking is a lot like asking "here is my data model; what should my web site look like?".

One way to look at that is to pay attention to caching, which is an important REST architectural constraint. You can look at the HTTP spec to understand how caching and cache invalidation work.

But the short form - if two pieces of information should be invalidated together, then they should be expressed in the representation of the same resource. If instead they have very different caching characteristics, then you probably want them separated, so that each can have its own caching meta data.

(Think "image in an html page"; its very common for a logo to have very different caching rules compared to the page content, so it makes sense for the logo to be a separate resource. On the other hand, if you have an image that is supposed to be synchronized with the content on the page, then you probably want to embed the image, rather than linking to it.)

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.