I am creating a RESTful JSON API to access data from our website where the content is in German.

A handful of the fields will return formatted HTML while most are single lines of text although they are highly like to include special characters.

To make it easy to use I wanted consistency throughout. As the text in the HTML fields would not be easy to encode after they have the data my first thought was to encode all fields (they can always be un-encoded later int he other fields).

Is this the best approach or should I suffix all the HTML fields e.g. description_html to imply they are already encoded or try something else?

The plan is let people use the API however they want although initially to let our partners use our data on their website.

  • Why is it difficult for the client to encode the raw data?
    – Max Nanasy
    Commented Feb 5, 2013 at 11:14

2 Answers 2


Generally a web service should return raw data, and a consuming application that embeds the data in a web page would encode the data it embeds. That way other applications that might display the data in a Windows application or do some other processing on it don't have to deal with html.

If the purpose of a service is really to provide formatted text and uses html to represent the formatting, then it should be marked as such. Though you should consider how a non web-page consumer would use that data.

  • 1
    I was thinking this hence the question. The data that is formatted starts as Markdown so I will provide that via the API then it's up to the consuming app. Thanks
    – John
    Commented Nov 3, 2011 at 8:28

It seems this depends on the intent of the API. Is it to provide formatted HTML to clients, or to provide data which the clients can use however they see fit?

If the purpose really is to provide consumable HTML, I would say to do the encoding. If it is to provide access to data, then don't.

If you really want to support both, perhaps different APIs (using the same back-end code) are in order -- one of which encodes, the other does not, but otherwise serving up the same fields, etc.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.