github.com/containers/podman/v2@v2.2.2-0.20210501105131-c1e07d070c4c/docs/tutorials/podman-derivative-api.md (about)

     1  ![PODMAN logo](../../logo/podman-logo-source.svg)
     2  
     3  # How to use libpod for custom/derivative projects
     4  
     5  libpod today is a Golang library and a CLI.  The choice of interface you make has advantages and disadvantages.
     6  
     7  Using the REST API
     8  ---
     9  
    10  Advantages:
    11  
    12   - Stable, versioned API
    13   - Language-agnostic
    14   - [Well-documented](http://docs.podman.io/en/latest/_static/api.html) API
    15  
    16  Disadvantages:
    17  
    18   - Error handling is less verbose than Golang API
    19   - May be slower
    20  
    21  Running as a subprocess
    22  ---
    23  
    24  Advantages:
    25  
    26   - Many commands output JSON
    27   - Works with languages other than Golang
    28   - Easy to get started
    29  
    30  Disadvantages:
    31  
    32   - Error handling is harder
    33   - May be slower
    34   - Can't hook into or control low-level things like how images are pulled
    35  
    36  Vendoring into a Go project
    37  ---
    38  
    39  Advantages:
    40  
    41   - Significant power and control
    42  
    43  Disadvantages:
    44  
    45   - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate)
    46   - Binary size
    47   - Potential skew between multiple libpod versions operating on the same storage can cause problems
    48  
    49  Varlink
    50  ---
    51  
    52  The Varlink API is presently deprecated. We do not recommend adopting it for new projects.
    53  
    54  Making the choice
    55  ---
    56  
    57  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?
    58  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
    59  different experience; if what you're doing with containers is quite different from those created by the `podman` CLI,
    60  that may drive you towards vendoring.