Well, in a REST interface, following HTTP where ever possible, I would return a 201 and an URI in the Location header field to the newly created Resource. Here is what Status Code Definitions says:
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URI for
the resource given by a Location header field. The response SHOULD
include an entity containing a list of resource characteristics and
location(s) from which the user or user agent can choose the one most
appropriate. The entity format is specified by the media type given in
the Content-Type header field. The origin server MUST create the
resource before returning the 201 status code. If the action cannot be
carried out immediately, the server SHOULD respond with 202 (Accepted)
response instead.
If something went wrong, I would argue you shouldn't return -1
as others have said, but simply a Client or Server Error Code (4xx or 5xx). For example, if a user is not allowed to create some new resource, you would simply return a "401 Unauthorized", nothing more and nothing less.
First of all, let's give your resource a name: let's call it a publication. This is to disambiguate it from another kind of resource your design is implying: the translation.
Second, let's agree to the fact that a collection of resources is also a resource itself. Having said that, a publication looks to me more like a collection of translations.
Third, using PUT
to create a translation seems inappropriate to me, because PUT
is used to replace a resource with another one. It would make sense if a translation to a specific language was already there, and the translator was updating it. But to create a new one, I think POST
suits best.
EDIT: I'm having second thoughts on the above. It appears that, since the id of the new resource is decided by the client, a PUT
would actually be appropriate after all. Maybe someone else could provide a more concrete opinion on the matter.
Now, considering the above, a uri structure like /publication/XYZ/en
would certainly make sense, because it would refer to the English translation of the publication with id XYZ. This resolves the creating/updating/deleting of translations (using POST
/PUT
/DELETE
resp.), while during a GET
request of /publication/XYZ
you could examine the Accept-Language
header and make the client redirect accordingly.
OTOH, your question clearly states that you want to treat the publication as a single resource. In that case, I guess you must treat translations as separate attributes (i.e. fields) of the same resource. Just as a person resource would have a first name, a last name and an e-mail, a publication could have a publication date, an English translation and a Japanese one.
But then you would have to find a way to partially update the publication when a translation would need to be created/edited. I guess a PATCH
request would be appropriate for this scenario.
Best Answer
This sounds like a pretty classic case of POST/Redirect/GET, and is sort of the expected behavior for web applications. I'd probably make that the default.
If you're not a fan of that approach for whatever reason, consider using AJAX (which means you can use the
PUT
approach mentioned by @sdg in a comment) with a standard 201 and the response body can contain the flash message to be displayed. The AJAX can do what you need it to do with the flash message, at that point.