2

suppose we have class below

class Blog {
    Integer id;
    List<Post> posts;
}

class Post {
     Integer id;
     List<String> tags;
}

If I want to make an endpoint for all tags of a certain blog, what is proper option. And return type is List.

blogs/{blog-id}/posts?field=tags

blogs/{blog-id}/post-tags

blogs/{blog-id}/posts/tags

blogs/{blog-id}/post/tags

Or any suggestion is fine. Which one is most approporiate?

applemango
  • 123
  • 1
  • 9

3 Answers3

1

Out of the ones you listed, I would opt for either the first or second, depending on use case.

blogs/{blog-id}/posts?field=tags: This indicates that you are wanting just the tags field for the items in the collection. I would expect there to still be an object per post in the response, but only the tags field to be present. If you wanted a distinct list, you would need to process those in the client.

blogs/{blog-id}/post-tags: This would be used to return a single, distinct list of tags applied.

Here is why I wouldn't go with the others:

blogs/{blog-id}/posts/tags: This would probably be viewed as a post titled tags instead of returning all the tags on posts.

blogs/{blog-id}/post/tags: In addition to the above, this implies a single post, not a collection.

Jacob Lambert
  • 7,449
  • 8
  • 27
  • 47
1

Which one is most approporiate?

REST doesn't care what spelling you use for your resource identifiers, so long as they are compliant with RFC 3986. The machines don't care -- as far as they are concerned, the URI are just cache keys, nothing more than that.

See also: Stefan Tilkov REST: I Don't Think It Means What You Think It Does.

Spelling conventions for URI are useful for humans; they are much like variable naming conventions, where we value familiarity and consistency in a given context, without absolutes on right and wrong.

blogs/{blog-id}/posts/tags
blogs/{blog-id}/post/tags

It might be useful to review the singular vs plural arguments for database table naming.

blogs/{blog-id}/posts?field=tags
blogs/{blog-id}/post-tags
blogs/{blog-id}/posts/tags

A reason that you might prefer the latter form is relative resolution, in particular the fact that you can use dot segments to express one identifier in terms of another.

blogs/{blog-id}/posts/tags + ../images -> blogs/{blog-id}/posts/images

There's no particular reason that the tags segment needs to be under posts, or even under blogs -- this spelling is also "fine", assuming that you don't run into problems with ambiguity:

/tags/{blog-id}
Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
0

Keep it consistent with the URI you have for posts. Lets assume you have the following;

/posts Returns links to all posts
/posts/tags Reads tags for all posts
/posts/id Reads a post
/posts/id/tags Reads the tags for a post

/blogs Returns links to all blogs
/blogs/id Reads a blog

Now if you want to read tags for all posts belonging to a blog it makes sense to chain the URIs together;

/blogs/id/posts/tags Reads tags for all posts belonging to blog.

Qwerky
  • 18,217
  • 6
  • 44
  • 80