CODEWITHSUNDEEP
restrelationshiprestful-architecture
Jevo Taren
Jevo Taren

Reputation: 179

REST - how to model relations with relation data

Say I have the following two root resources:

.../organizations
.../persons

A GET on .../organizations/id returns all the information about a specific organization, such as the name, location, etc.

A GET on .../persons/id returns all the information about a specific person, such as the name, age, gender, etc.

What is the preferred RESTful way to model the membership of a person in an organization (for retrieval and creation)? I do not only want to model the membership itself, but also add extra properties, such as the date on which the person joined the organization, his/her role in the organization, ...

Some thoughts:

Upvotes: 4

Views: 735

Answers (3)

David Brabant
David Brabant

Reputation: 43489

Wouldn't using HAL and its simple format fulfil your needs?

Let's suppose we have defined resources for persons, organizations and memberships and we are attempting to retrieve information related to a person identified by "42".

Request:

GET /persons/42 HTTP/1.1
Accept: application/hal+json

Response:

HTTP1.1 200 OK
Content-Type: application/hal+json
{
    "id": 42,
    "name": "Smith",
    "firstName": "John",

    "organization": {
        "id": 1234,
        "name": "blah",
        "href": "http://myserver/organizations/1234"
    },

    "membership": {
        "id": 5678,
        "name": "blih",
        "href": "http://myserver/memberships/5678"
    },

    "_links": {
        "self" : {
            "href" : "http://myserver/persons/42"
        }
    }
}

The person resource refers to the parent organization through the "organization" relation. That relation allows you to easily navigate to the corresponding organization resource through the corresponding href link.

In the same manner, the membership relations allows to access the corresponding membership data (once again through the "href" link), if you consider that membership associates one person to one organization.

Request:

GET /memberships/5678 HTTP/1.1
Accept: application/hal+json

Response:

HTTP1.1 200 OK
Content-Type: application/hal+json
{
    "id": 5678,
    "name": "blih",

    "person": {
        "id": 42,
        "href": "http://myserver/persons/42"
    },

    "organization": {
        "id": 1234,
        "href": "http://myserver/organizations/1234"
    },

    "_links": {
        "self": {
            "href": "http://myserver/memberships/5678"
        }
    }
}

Please note that I'm not saying that the modelisation above is the right one for your needs (one person can probably belong to several organizations, for example, and you then need an array in the serialization).

My point is that using HAL might help you modelize what you want.

Upvotes: 3

bitoiu
bitoiu

Reputation: 7474

Think of a resource an object that could exist independently without a dependency to another object. This is just a guideline and you can see how it works in terms of your projects and organizations.

The way I see it a membership should be it's independent resource, because it could even exist after the resource person has been deleted, for historical purposes for example.

In that model I would create a resource /memberships, because it's not a property of a person or an organization that would prompt you to add that as a person or organization sub-resource.

I'm not sure if I agree with @hellraiser, perfect would be hard to define even by Roy's standards. I usually try to achieve the higher level of REST as described by Fowler: http://martinfowler.com/articles/richardsonMaturityModel.html

Upvotes: 0

hellraiser
hellraiser

Reputation: 1451

Actually, perfect RESTful API design is unreachable. I've never seen a system that satisfies all REST API theses formulated by Roy Fielding. But you can improve your skills of rest api design from project to project by following best practises. For the first time, look this article.

Upvotes: -1

Related Questions