How to improve my REST API?

Question

I have some questions regarding my REST API that's still in development.

I have the following endpoints:

• /users.json: shows a list of all the users
• /users/$username.json: shows a single user resource
• /posts.json: shows a list of all the posts
• /posts/$post_id.json: show a single post resource

A single post resource looks like this:

{"path": "http://api.myproject.com/posts/1.json", "id": 1, "author": "http://api.myproject.com/users/kristof.json", "image": "/images/posts/cxyUzlPo.jpg", "date": "2014-11-09 15:16", "likes": "http://api.myproject.com/posts/1/likes.json", "comments": "http://api.myproject.com/posts/1/comments.json", "likes_count": 0, "comments_count": 0}

As you can see, a post contains a field "author", which defines a hyperlinked relationship to a single user resource.

Now the following problem occurs: I want to build a feed of all the posts created by users. That's easy: I just call the /posts.json endpoint and I have all my posts... But when I want to show the author information about every post, then I would have to make an extra HTTP REST call for every post in the list? That seems very inefficient and bad for performance to me?

Now of course, you can also add the author resource as a nested resource in the list of post resources, but is this still regarded as "RESTful"?

The longer I'm busy building REST APIs (the more I'm learning, obviously), but the more I have to make decisions between "pragmatic REST" and "REST as a religion". :-)

Thanks in advance for any help!

Kind regards, K.

Answer 1

You can include author information for every post in a call to /posts/ and it's still RESTful. The issue then becomes how to include this information. Please have a look at JSON HAL and read about embedded resources.