summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthew Heon <matthew.heon@pm.me>2020-05-20 17:35:24 -0400
committerMatthew Heon <matthew.heon@pm.me>2020-05-20 17:35:24 -0400
commit9ceff66a7dc99553afdf59151e1995ed30c9b26c (patch)
tree1f7577d86d3f80d42cac5327d3b421416cc8824f
parente8e5a5f96e0b5d915baeeb0915cc0ca788b70e64 (diff)
downloadpodman-9ceff66a7dc99553afdf59151e1995ed30c9b26c.tar.gz
podman-9ceff66a7dc99553afdf59151e1995ed30c9b26c.tar.bz2
podman-9ceff66a7dc99553afdf59151e1995ed30c9b26c.zip
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>
-rw-r--r--docs/tutorials/podman-derivative-api.md18
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.