API responsibilities

[Nicolas Faugout]

When a user is created through a web interface, there is often a notification email send to hi by the server handler.

If that same user is created by sending a POST to an API, should it be the API that sends the email or the service that called the API ?

I would say :

- by default, the API should send the email since it can be considered as a part of the entire process (inserting an entry into a database table, creating a log entry in a log file, sending a notification email, ...)

- but the API should also give the opportunity not to send email because this part of the process is in fact not mandatory. For instance, when creating several users with a bulk request and delaying the email when the service is really opened to them.

POST /api/users => create the user and sends the email

POST /api/users?noNotification => create the user

Any suggestion would be grateful.

[Luke Stokes]

On Tuesday, November 13, 2012 7:47:05 AM UTC-6, Nicolas Faugout wrote:

When a user is created through a web interface, there is often a notification email send to hi by the server handler.

If that same user is created by sending a POST to an API, should it be the API that sends the email or the service that called the API ?

I would say :

- by default, the API should send the email since it can be considered as a part of the entire process (inserting an entry into a database table, creating a log entry in a log file, sending a notification email, ...)

Yeah, I'd think about it this way also. I wonder if someone has a differing opinion...?

 

- but the API should also give the opportunity not to send email because this part of the process is in fact not mandatory. For instance, when creating several users with a bulk request and delaying the email when the service is really opened to them.

Interesting. In this case, you'd have to keep track of who was emailed and who wasn't so you could send the follow up email, right? Maybe you could argue for "welcome_email_sent" as a property of your user. If it is, POSTing with welcome_email_sent = 1 could send the email and 0 could avoid it. If someone loses there welcome email and wants another one, you could even build in a process to PATCH it back to 0 and then to 1 again (thus, triggering another welcome email).

 

POST /api/users => create the user and sends the email

POST /api/users?noNotification => create the user

This works also, but you'd either have to document it out of bounds so the client knows to add that magic bean to the href it got back from the create user rel or you'd provide two different rels to point to your different uris:

rel="http://example.com/rels/create_user" href="/api/users"

rel="http://example.com/rels/create_user_no_notification" href="/api/users?noNotification"

 

Any suggestion would be grateful.

Those are my suggestions. Not sure if they're helpful. :) 

[Nicolas Faugout]

Hi Luke,

I think you are right advising me to have a welcome_email_sent boolean attached to the user resource, that one is missing in my model !

This way, as you said, it is very easy to make the API send or not send the email when creating a new user.

It seems common in REST APIs to make the API do an action by trying to update the resource attribute corresponding to that action.

I will stick with that idea and throw the noNotification parameter away, event if it has a scope wider than just the welcome email of creating a user.

Thank you.

[Glenn Block]

I would probably keep it as part of the POST Body. After all the POST is a request to create a resource so including additional details like sending an intro mail seems very reasonable.

One thing you could do for the delayed sending is have the response contain a link to send the mail. This way if I create 10 users, I get back 10 different links.

An alternative for the batch create is to actually model that at the resource level. You can have a resource which you post multiple users to. That resource can then either automatically send a mail once the batch is completed, or it can return a location header that points to a resource that has a link for sending all the mails.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Nicolas Faugout]

Thank you for the precisions.

Speaking about the batch request, do you have any good practice to follow ? I have a bunch of types of resources that should support a batch creation. Is there any other option than creating a special resource for handling the batch capability of each resource ?

PS : This question should probably go into another thread since it has nothing to deal with API responsibility, but I am new to API Craft so I don't know yet if we can let the discussion switch to other debates or not in the same thread ;)

To unsubscribe from this group, send email to api-craft+unsubscribe@googlegroups.com.

[Rob Mullen]

Batch processing has been discussed, search around and see what you can find first, if you can't find anything, post another question.  

As for your topic I would not make the notification email part of the user creation process, and certainly not part of the resource body, I can't imagine why you'd want a user to have a "send_welcome_email" property.   When first building services it's always best to start finely grained, build a send email service, and a create user service, then let the client call both of them if they want.  If this use case proves to be common, you could look into creating a service aggregation layer that combined the two of them for ease of client consumption.  It's easy to go from finely grained to coarsely grained services, not so easy the other way.

Rob

[Nicolas Faugout]

Hi Rob,

Thank you for your answer, which doesn't seem to go in the same way as Luke and Glenn.

In your approach, there is three independants parts in the system : the client, the API, the email service.

The problem is that the email sent when creating a new user is not of the choice of the client.

For me, it is the API that hosts the email because, for instance, the API is the only part to know the user password, that has probably been generated in the creation process. Nor the client or the email service knows the clear text password of the user.

So I would say that the API acts as a Façade for the client, hiding the email service that is behind the API.

In short, the API has its own email service and the client should decide whether or not to user it. It can also use an other email service, one of his own, but should know that it won't have full information, like the password.

Do you have an idea on how to deal with this problem ?

Thanks

[Glenn Block]

Having a property as part of the POST body does not require it to be part of the persisted resource state. I agree with you Rob that I should not do a GET on the User and see that they request an email notification on creation. 

Having multiple APIs like an email API is certainly an option, but I don't see the two as mutually exclusive, you can have both.

It all depends on the usage of the system. If sending mails is very common on creation of the user then having the server handle it reduces complexity for the user. 

To unsubscribe from this group, send email to api-craft+...@googlegroups.com.

[Glenn Block]

Nicholas

There are different approaches to batching. I prefer having an explicit message format that allows me to send 1 to n items that I want created. An alternative approach is actually encapsulating multiple requests in a multi-part request where each part is of type message/http and is a fully encapsulated request message. The server then replays each message. I prefer the simple approach which IMO is the first and not using HTTP batching.

Aside fromt that, the main rule i would follow for batching is to make sure the batch creation is async i.e. when a POST to a batch, the server returns me a location header with a url where I can poll to check on the processing of the batch.

To unsubscribe from this group, send email to api-craft+...@googlegroups.com.

[Nicolas Faugout]

Thank you Glenn.

It is clear to me now, especially the async batching, that's a great idea !

[PJD1328]

I like Rob's last reply with little difference. We have done almost same for SOAP services but can be applied to REST.

What we have is

User Service (to create User resource)
Email Service (to Just send email...in dependent of who is calling)
User Service Event Handler (a code which picks event from user service and collect rest of the data and call Email Service in back end)

So the whole process flow is ...

Client ---> User Service (up on successfully creating resource sends JMS event)--> event is listened by Handler (once receive event collect rest of data) ---> call Email service if needed

You can change few of the stuff here like user service sends JMS message only if client has flag or Event handler can call email service only if flag is there

You can have flag has part of your business process and configuration (your choice)

Benefits are , response to client is faster (as they don't have to wait for email processing to finish)
If email fails or Handler fails because of any reason, you can reprocess that event message
If Email structure or provider changes, no change in User Service

[Robert Daniel Pickard]

Hi Nicolas et al,

If you are writing a REST API, I think a PUT would be more appropriate than a POST call when creating a new user. That way you can have distinct  logic for adding a new user (PUT) and updating an existing user (POST).

Is the purpose of the notification email to send the new user a greeting or is it to verify that the email that was submitted on creation of the new user valid and owned by the individual signing up? If the email is just a greeting, I would agree with most of the other folks that a batched job would be fine; the user of the site is not affected whether or not the greeting is read.

However, if the email is to validate the email address that is submitted, I think a batched send might incur a lot more baggage. Either you'd have to support users with partial validation state (perhaps with fewer privileges than a fully validated user) or you'd have to force users to wait until the batch process was run which could be a diminished user experience.

In either case you could take advantage of a well implemented API and have your email'ing code update the users state with a POST call. It would update the user resource to chance the property 'email_validated' to True or something similar.

Best of luck!
rdp

On Tuesday, November 13, 2012 8:47:05 AM UTC-5, Nicolas Faugout wrote: