What's the ideal way to send a success message in the response of a HATEOAS Rest Api?

Question

I am using HATEOAS architecture in my rest application and want to send internationalized success message that will be directly consumed by the client. I know we can just add a key in the response but want to know what is the ideal way architecturally.

For example, lets say i want to send a message Department created successfully in my response below. How would i go about that?

Uri: http://api.domain.com/management/departments
Type: POST

Existing response:

{
    "departmentId": 10,
    "departmentName": "Administration",
    "locationId": 1700,
    "managerId": 200,
    "links": [
        {
            "href": "10/employees",
            "rel": "employees",
            "type" : "GET"
        }
    ]
}

Answer 1

Remember, you are not sending messages from the server to the clients. You are sharing resources. Representations of resources you have somewhere. More specifically, their status. A projection of them. The client is "asking" for something you have in your server and the server is sharing a temporal representation of it.

The fact that the server did response (200, 201, etc) and the client got a representation is enough confirmation (message) for you. So if the client application handles a 20x, you can show the message you want. The server doesn't care whether the client got the response or not.

Regarding the result of the "communication" process, leave it to the protocol and its semantics. Use HTTP status code, headers and response messages according to the request methods, headers, etc.

Why?

Because the main consumers of the HTTP requests and responses are an HTTP client and an HTTP server that will react and behave according to these things. You get the most out of HATEOAS, If you don't introduce noise in the communication process and respect the protocol semantics.

Answer 2

What's the ideal way to send a success message in the response of a HATEOAS Rest Api?

How would you do that with a web site?

You'd send the message in the body of the HTTP response. You would use some standardized media type (like HTML), that allows you to articulate the semantics of the message to the client. You'd probably also include in the response links to other steps in the domain application protocol.

The metadata, being the headers and the status-line of the response, would give general purpose components (like browsers) information about the response in standardized forms.

The pattern is the same when you are working machine to machine -- the only real difference is that machines don't (generally) have human adaptability. So you need to specify the message schema, so that the client knows where to look in the response for the information that it needs.

Answer 3

If the server created the object, then it should send a 201 created status code, and a Location header that points to the new created object, e.g. http://api.domain.com/management/departments/1.

The client application, seeing the 201 created status, can then display the appropriate message in the user's chosen language. Internationalisation like this happens on the client application. In other words, the client should know what to do next after the server fulfilled the request.

Answer 4

Like a lot of similar things in HTTP you do this via content negotiation.

HTTP protocol defines the header Accept-Language that the client passes to the server. This header contains a list of the languages (as in natural language, not programming language) that it understands.

The server can then select the most appropriate language (or fall back to a default if it doesn't support any of the ones the client requests).

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

This is how you handle which language to return responses in.

As other answers point out you should still use the standard HTTP response codes, but the body of the response should be translated to the language negotiated by this process.

So request is

POST /management/departments HTTP/1.1
Host: api.domain.com
Accept-Language: en-US
Content-Type: application/json

{...JSON body here}

and response is

HTTP/1.1 201 Created
Date: Thu, 10 Oct 2019 10:36:20 GMT
Server: Apache/2.2.14 (Win32)
Content-Language: en-US
Location: http://api.domain.com/management/departments/123

Department created successfully

and if the Accept-Language has been say es-AR

POST /management/departments HTTP/1.1
Host: api.domain.com
Accept-Language: es-AR
Content-Type: application/json

{...JSON body here}

the response would be (apologies for the butchered Google Translate Spanish attempt)

HTTP/1.1 201 Created
Date: Thu, 10 Oct 2019 10:36:20 GMT
Server: Apache/2.2.14 (Win32)
Content-Language: es-AR
Location: http://api.domain.com/management/departments/123

Departamento creado con éxito