CODEWITHSUNDEEP
web-servicesrest
Martin Hansen
Martin Hansen

Reputation: 2101

RESTservice, resource with two different outputs - how would you do it?

Im currently working on a more or less RESTful webservice, a type of content api for my companys articles. We currently have a resource for getting all the content of a specific article

http://api.com/content/articles/{id}

will return a full set of article data of the given article id.

Currently we control alot of the article's business logic becasue we only serve a native-app from the webservice. This means we convert tags, links, images and so on in the body text of the article, into a protocol the native-app can understand. Same with alot of different attributes and data on the article, we will transform and modify its original (web) state into a state that the native-app will understand.

fx. img tags will be converted from a normal <img src="http://source.com"/> into a <img src="inline-image//{imageId}"/> tag, samt goes for anchor tags etc.

Now i have to implement a resource that can return the articles data in a new representation

I'm puzzled over how best to do this.

  1. I could just implement a completely new resource, on a different url like: content/articles/web/{id} and move the old one to content/article/app/{id}

  2. I could also specify in my documentation of the resource, that a client should always specify a specific request header maybe the Accept header for the webservice to determine which representation of the article to return.

  3. I could also just use the original url, and use a url parameter like .../{id}/?version=app or .../{id}/?version=web

What would you guys reckon would be the best option? My personal preference lean towards option 1, simply because i think its easier to understand for clients of the webservice.

Regards, Martin.

EDIT:

I have chosen to go with option 1. Thanks for helping out and giving pros and cons. :)

Upvotes: 0

Views: 45

Answers (4)

Jason Desrosiers
Jason Desrosiers

Reputation: 24489

Option 1 and Option 3

Both are perfectly good solutions. I like the way Option 1 looks better, but that is just aesthetics. It doesn't really matter. If you choose one of these options, you should have requests to the old URL redirect to the new location using a 301.

Option 2

This could work as well, but only if the two responses have a different Content-Type. From the description, I couldn't really tell if this was the case. I would not define a custom Content-Type in this case just so you could use Content Negotiation. If the media type is not different, I would not use this option.

Upvotes: 1

johnml
johnml

Reputation: 428

I would choose #1. If you need to preserve the existing URLS you could add a new one content/articles/{id}/native or content/native-articles/{id}/. Both are REST enough.

Working with paths make content more easily cacheable than both header or param options. Using Content-Type overcomplicates the service especially when both are returning JSON.

Upvotes: 2

user1907906
user1907906

Reputation:

Use the HTTP concept of Content Negotiation. Use the Accept header with vendor types.

Get the articles in the native representation:

GET /api.com/content/articles/1234
Accept: application/vnd.com.exmaple.article.native+json

Get the articles in the original representation:

GET /api.com/content/articles/1234
Accept: application/vnd.com.exmaple.article.orig+json

Upvotes: 2

morsor
morsor

Reputation: 1323

Perhaps option 2 - with the header being a Content-Type?

That seems to be the way resources are served in differing formats; e.g. XML, JSON, some custom format

Upvotes: 0

Related Questions