Home/ Questions/Q 693079
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-14T02:43:01+00:00

I’m currently (I try to) designing a RESTful API for a social network. But

  • 0

I’m currently (I try to) designing a RESTful API for a social network. But I’m not sure if my current approach does still accord to the RESTful principles. I’d be glad if some brighter heads could give me some tips.

Suppose the following URI represents the name field of a user account:

people/{UserID}/profile/fields/name

But there are almost hundred possible fields. So I want the client to create its own field views or use predefined ones. Let’s suppose that the following URI represents a predefined field view that includes the fields “name”, “age”, “gender”:

utils/views/field-views/myFieldView

And because field views are kind of higher logic I don’t want to mix support for field views into the “people/{UserID}/profile/fields” resource. Instead I want to do the following:

utils/views/field-views/myFieldView/{UserID}

Another example

Suppose we want to perform some quantity operations (hope that this is the right name for it in English). We have the following URIs whereas each of them points to a list of persons — the friends of them:

GET people/exampleUID-1/relationships/friends
GET people/exampleUID-2/relationships/friends

And now we want to find out which of their friends are also friends of mine. So we do this:

GET people/myUID/relationships/intersections/{Value-1};{Value-2}

Whereas “{Value-1/2}” are the url encoded values of “people/exampleUID-1/friends” and “people/exampleUID-2/friends”. And then we get back a representation of all people which are friends of all three persons.

Though Leonard Richardson & Sam Ruby state in their book “RESTful Web Services” that a RESTful design is somehow like an “extreme object oriented” approach, I think that my approach is object oriented and therefore accords to RESTful principles. Or am I wrong?

When not: Are such “object oriented” approaches generally encouraged when used with care and in order to avoid query-based REST-RPC hybrids?

Thanks for your feedback in advance,

peta

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    Hi peta,
    I’m still reading through RESTful Web Services myself, but I’d suggest a slightly different approach than the proposed one.

    Regarding the first part of your post:

    utils/views/field-views/myFieldView/{UserID}

    I don’t think that this is RESTful, as utils is not a resource. Defining custom views is OK, however these views should be (imho) a natural part of your API’s URI scheme. To incorporate the above into your first URI example, I would propose one of the following examples instead of creating a special view for it:

    people/{UserID}/profile/fields/name,age,gender/
people/{UserID}/profile/?fields=name,age,gender

    The latter example considers fields as an input value for your algorithm. This might be a better approach than having fields in the URI as it is not a resource itself – it just puts constraints on the existing view of people/{UserID}/profile/. Technically, it’s very similar as pagination, where you would limit a view by default and allow clients to browse through resources by using ?page=1, ?page=2 and so on.

    Regarding the second part of your post:
    This is a more difficult one to crack.

    First:
    Having intersection in the URI breaks your URI scheme a bit. It’s not a resource by itself and also it sits on the same level as friends, whereas it would be more suitable one level below or as an input value for your algorithm, i.e.

    GET people/{UserID}/relationships/friends/intersections/{Value-1};{Value-2}
GET people/{UserID}/relationships/friends/?intersections={Value-1};{Value-2}

    I’m again personally inclined to the latter, because similarly as in the first case, you are just constraining the existing view of people/{UserID}/relationships/friends/

    Secondly, regarding:

    Whereas “{Value-1/2}” are the url
    encoded values of
    “people/exampleUID-1/friends” and
    “people/exampleUID-2/friends”

    If you meant that {Value-1/2} contain the whole encoded response of the mentioned GET requests, then I would avoid that – I don’t think that the RESTful way. Since friends is a resource by itself, you may want to expose it and access it directly, i.e.:

    GET friends/{UserID-1};{UserID-2};{UserID-3}

    One important thing to note here – I’ve used ; between user IDs in the previous example, whereas I used , in the fields example above. The reasoning is that both represent a different operator. In the first case we needed OR (,) in order to get all three fields, while in the last example above we had to use AND (;) in order to get an intersection.

    Usage of two types of operators can over-complicate the API design, but it should provide more flexibility in the end.

    • 0