Is 202 Accepted appropriate when a resource awaits email confirmation/activation?

Question

For a REST API I'm developing, a client is able to register a company, which subsequently needs confirmation/activation through email. After the following example request is received, an email is sent with an activation link in it, to activate the account.

POST /companies HTTP/1.1

<company>
  <name>CoolCompany</name>
  <email>[email protected]</email>
</company>

If the above request was successful (valid data, email successfully sent), the company resource is saved in the database, but will only be available at /companies/<id> (given an appropriate Authorization header) after confirmation is received.

Given this scenario, is

HTTP/1.1 202 Accepted
// Perhaps optionally with a Location header, 
// of where the resource will be available, as well?
Location: /companies/<id>

an appropriate response? Or would

HTTP/1.1 201 Created
Location: /companies/<id>

be a more appropriate response?

Answer 1

REST is an entity based consept. If I got a 201 Created response, this would intuitively suggest that the resource has been created and is available, which is not this case. The resource is first available after the confirmation, and I would therefore suggest using the 202 Accepted header.

In addition, you can not be sure that the user has received the email at the request time. I like using 202 Accepted in cases like these (SMS, Email etc), because it tells the API consumer that it was a valid request, but it might take some time before it is done.

Answer 2

My idea is:

201 - is when all the stuff/processing is completed in the end of request (DB populated, files created etc), so when client (event immediately) GET the resource, he will receive it complete.

202 - is when request is received and successfully started processing but according to some restrictions of process no all request related activities processed.

In you case:

if send email synchronously and don't return response until email sent, than I guess 201(Created) is OK

if for example you set email sending task into queue and return to client immediately and email may be sent a little bit later (or for example there is some manual processing of new clients by operator before sending email) than 202 is better.