+The functions of the v2:
+
+```C
+int (*preinit)();
+int (*init)();
+void (*onevent)(const char *event, struct json_object *object);
+```
+
+Gain a new first argument of type **afb_api_t** as below:
+
+```C
+int (*preinit)(afb_api_t api);
+int (*init)(afb_api_t api);
+void (*onevent)(afb_api_t api, const char *event, struct json_object *object);
+```
+
+For the migration, it is enough to just add the new argument without
+using it.
+
+Consider use of the new reply
+-----------------------------
+
+The v3 allows error reply with JSON object. To achieve it, an unified
+reply function's family is introduced:
+
+```C
+void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info);
+void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args);
+void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...);
+```
+
+The functions **success** and **fail** are still supported.
+These functions are now implemented as the following macros:
+
+
+```C
+#define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i)
+#define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__)
+#define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v)
+#define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i)
+#define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__)
+#define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v)
+```
+
+This is a decision of the developer to switch to the new family
+**afb_req_reply** or to keep the good old functions **afb_req_fail**
+and **afb_req_success**.
+
+Consider use of the new (sub)call
+---------------------------------
+
+The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**,
+**afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned
+to better fit the new reply behaviour. In most case the developer will benefit
+of the new behavior that directly gives result and error without enforcing
+to parse the JSON object result.
+
+The subcall functions are also fully redesigned to allow precise handling
+of the context and event subscriptions. The new design allows you to specify:
+
+ - whether the subcall is made in the session of the caller or in the session
+ of the service
+ - whether the credentials to use are those of the caller or those of the
+ service
+ - whether the caller or the service or both or none will receive the
+ eventually events during the subcall.
+
+See [calls](reference-v3/func-api.html#calls-and-job-functions) and
+[subcalls](reference-v3/func-req.html#subcall-functions).
+
+The table below list the changes to apply:
+
+| Name in Version 2 | New name of Version 3
+|:----------------------:|:----------------------------------------------------:
+| afb_req_subcall | afb_req_subcall_legacy
+| afb_req_subcall_sync | afb_req_subcall_sync_legacy
+| afb_service_call | afb_service_call_legacy
+| afb_service_call_sync | afb_service_call_sync_legacy
+| afb_req_subcall_req | afb_req_subcall_req (same but obsolete)
+
+
+Consider use of event handlers
+------------------------------
+
+Binding V3 brings new ways of handling event in services. You can register
+functions that will handle specific events and that accept closure arguments.