Shoud I directly return a string message or rather a i18n key when dealing with JSON api?

Question

Suppose a rest api returning this json:

{
    "status" : "fail",
    "data" : { "title" : "A title is required" }
}

Since the client application would always adapt the error message, would it be better to return an explicit i18n key that the client would have mapped rather than "A title is required"? :

{
    "status" : "fail",
    "data" : { "title" : "error.creation.title.required" }
}

Indeed, the point is to expect the request consumer (web application for instance) to easily translate the message regarding its localization.

Answer 1

1. If you were defining common error format for your Api, see also "Problem Details for HTTP APIs". You don't need to say "status: fail" because it should be indicated already in status code. You can use "problemType" URI as key.

2. For clients that don't want to translate error message themselves, they should use Accept-Language header so server knows what language it needs to speak.

Answer 2

One way to go would be to include a flag in your request if the user wants to have an i18n key.

host/page?somrequest=somevalue&flagi18n=true

Seeing this flag, you may then let your API return the i18n key. Otherwise, you return the message in the default language.

This way, you keep your API decoupled from the client. For me, this is a matter of preference.