7

I'm struggling to find an answer to this (perhaps because I'm not asking the question properly) ...

I'm building API to expose resources for a basic social networking service I'm creating. My understanding is that the structure of URLs in an API is essentially a hierarchy, directory like structure. I think that means I can have multiple endpoints to reach the same resources or collections of resource links. For example:

I have an endpoint

www.domain.api.org/users/{:uid}/posts

Which will return all posts sent by the user or that the user is tagged in. Seems ok, but what if I have an endpoint such as:

www.domain.api.org/posts

Which when hit with a http GET will return all public posts (i.e. all users' posts plus his friends' and public posts).

The difference is that the first URL points to user owned resources whereas the second to public ones (of which the users posts are included of course) Are these okay or am I doing it the wrong / less sensible way?

To reiterate, can I have multiple endpoints which point to different contexts/views of the same resource?

David Fang
  • 1,777
  • 1
  • 14
  • 19
apostrophedottilde
  • 867
  • 13
  • 36

3 Answers3

7

Basically multiple endpoints for the same resources should be avoided. However in this particular case it does make sense.

What you can do is to introduce optional query param userId to the following endpoint:

www.domain.api.org/posts/?userId=<userId>

If this substitutes the first endpoint you mentioned that's the way to go.

Opal
  • 81,889
  • 28
  • 189
  • 210
  • Thanks. Nice answer. Its made me rethink my approach to url design completely. In particular, it just didnt make sense at all to have users/:uid in any of the urls as the only the logged in and authenticated user can look at the resources of that user anyway, so i just keep the logged in user id in the access token (jwt) created after a successful login. – apostrophedottilde Dec 26 '15 at 13:58
  • I thought that was worth pointing out for anybody else like me thats still gettjng to grips with good url endpoint design. – apostrophedottilde Dec 26 '15 at 13:59
  • 3
    Why **should be avoided**? Any studies, resources, standards,.. backing this statement? What happens, if this "should" is not followed? And, based on project specific architecture, it might even be **multiple endpoints should be used**. The **should** opinion is purely subjective, unless backed by reasoning within some context. – kravemir Dec 12 '19 at 09:19
3

I would like to add ontop of @Opal's answer.

Are these okay or am I doing it the wrong / less sensible way?

Ideally, like Opal mentioned, you would use queryParams in your url. For many applications I have build, I don't know the uids returned from the api beforehand, so selecting an item and passing it inside my url as a query parameter makes sense. But it also has the added benefit of having your key inside your url, allowing you to bookmark it, pass the url to another user and they will automatically see the same data you want them to see.

To iterate: Is your current implementation wrong? No, but ideally you would use a combination of both route parameters are query parameters to achieve this

Maartenw
  • 595
  • 1
  • 5
  • 19
0

To create an endpoints, you have to be sure that you have these information at once:

  • Name of the endpoint
  • Status: activate or not (required) - is the endpoint activated or disable
  • Service profile (required) - ID of the Service Profile assigned to the endpoint.
  • Tariff profile (required) - ID of the tariff Profile assigned to the endpoint.

You can add another optional informations, and be sure of the structure of your endpoint. Hope this helps you.

BackToReal
  • 143
  • 1
  • 5
  • 15