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"
        }
    ]
}

HTTP has standard response codes for these things. I'd say, don't overthink it, return a `201 created` if a department has been created. [Mozilla Guide to HTTP statuses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) — Chris Murray, Oct 09 '19 at 13:39

score 3 · Accepted Answer · edited Oct 07 '21 at 07:34

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.

I thought so much as well. The implementation would have been much easier at the client side if i could send these translated messages from the server but that doesn't seem to be the standard practice. Thank you!! — Gajender Parmar, Oct 12 '19 at 05:21

score 1 · Answer 2 · answered Oct 09 '19 at 12:35

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.

score 1 · Answer 3 · edited Oct 10 '19 at 09:19

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.

score 0 · Answer 4 · answered Oct 10 '19 at 12:35

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

What you said is true for conventional rest application. But in hateoas, for a POST request, you send the actual object(resource) that was created along with the 201 status. We are using Accept-Language header option to translate the object body, but i wanted to add another field in the response which is not part of the resource properties. Hence my confusion around how it should be done. — Gajender Parmar, Oct 12 '19 at 05:15
Ok there is a bit to unpack here. HATEOAS is a principle of REST. They are two sides of the same coin. Neither say anything about what should be returned from a POST request. The HTTP spec defines that. The 201 response code says you _can_ send a representation of the object or objects created, or you can just send links to them (see in my example the `Location` header). If you want to send the actual object that is fine, but your example wanted to return some message. Nothing in the HTTP spec says you _can't_ do this, just so long as you give some way to find the newly created objects. — Cormac Mulhall, Oct 15 '19 at 13:47
From the HTTP spec `The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI. The 201 response payload typically describes and links to the resource(s) created.` The payload is the body of the request returned. It is rather undefined by the spec, it _typically_ describes and links to the resource(s) created but it doesn't have to. Maybe a better question is what exactly you want to achieve here. — Cormac Mulhall, Oct 15 '19 at 13:50

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

4 Answers4