Update Derivative API tutorial to reflect the HTTP API

Once the HTTP API becomes stable, I think we want to drive people
towards using it, as opposed to directly calling our CLI (when
possible).

Signed-off-by: Matthew Heon <matthew.heon@pm.me>

1 files changed, 16 insertions, 2 deletions

diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md
index 065b0c4a9..8a1f40fc0 100644
--- a/docs/tutorials/podman-derivative-api.md
+++ b/docs/tutorials/podman-derivative-api.md
@@ -4,6 +4,20 @@
 
 libpod today is a Golang library and a CLI.  The choice of interface you make has advantages and disadvantages.
 
+Using the REST API
+---
+
+Advantages:
+
+ - Stable, versioned API
+ - Language-agnostic
+ - [Well-documented](http://docs.podman.io/en/latest/_static/api.html) API
+
+Disadvantages:
+
+ - Error handling is less verbose than Golang API
+ - May be slower
+
 Running as a subprocess
 ---
 
@@ -35,12 +49,12 @@ Disadvantages:
 Varlink
 ---
 
-Some code exists for this; splits the difference.  Future uncertain.
+The Varlink API is presently deprecated. We do not recommend adopting it for new projects.
 
 Making the choice
 ---
 
 A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project?
-If so, that makes it more likely that you want to run `podman` as a subprocess.  If you want a separate image store and a fundamentally
+If so, that makes it more likely that you want to run `podman` as a subprocess or using the HTTP API.  If you want a separate image store and a fundamentally
 different experience; if what you're doing with containers is quite different from those created by the `podman` CLI,
 that may drive you towards vendoring.