Open-source project
pistacheio/pistache avatar
pistacheio/pistache

Pistache: a C++17 REST framework whose best documentation is its own version policy

A high-performance REST toolkit written in C++

3,467 stars711 forksC++Apache-2.0

At a glance

What is it?
A header-driven HTTP and REST framework for C++ with precompiled packages for most distributions, two build systems, and a versioning section that explains exactly when to bump the interface number. The API documentation, by the project's own statement, is still incomplete.
Who is it for?
Use Pistache if you are writing a C++ service and want a REST layer that does not drag a web framework's runtime into your build. It ships precompiled packages for the main Linux distributions and macOS, so the cost of adopting it is low, and its interface versioning is documented well enough to package safely.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pistacheio/pistache3,467 ★ · -2
Star history
Repository2026-09-242026-11-15
pistacheio/pistache3.5k3.5k

-2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A pure C++17 framework whose API docs are admittedly partial

The description is a C++ HTTP and REST framework written entirely in a single language standard, with an API it describes as clear and pleasant.

Platform support is stated in one line: Linux, macOS, Windows, and three BSDs by name. And then the practical part, which is that the build instructions are per platform, as text files in the repository root: one for macOS, one for Windows, one covering the BSDs, another for macOS using the other build system, and a further file on the macOS implementation specifically.

Those filenames are worth noticing on their own. Documentation files with spaces and commas in their names, at the root of a C++ library, are the shape of a project where documentation is contributed by whoever has the platform in front of them.

On the API itself the statement is unusually candid: the project is still looking for a volunteer to document it fully, partial documentation is published at the project site, and interested people are invited to open an issue. So a reader deciding whether to adopt this is being told the manual is unfinished, which is more useful than discovering it later.

There is also a third-party benchmark comparing it against other C++ REST options, linked from the same section. It is somebody else's measurement, not the project's, and the project links it rather than quoting numbers.

The versioning section is the best documentation here

One section runs longer than the rest of the introduction combined, and it is about library versioning rather than about REST.

The first point is that the interface version is not the same as the release version. They plan to guarantee that the major release version and the shared object name version match once the project reaches one, and until then the shared object name version follows feature releases. So today, a feature release can change the name your linker records.

The second point is that the interface version is mainly about the external interface, and that platforms handle this differently, with three named as examples. That is why the file naming convention below is explained rather than assumed.

The third is the toolchain consequence. The build uses Meson, and the portability layer that normally handles symbol exports and archive tooling is not supported there, so the project sets the shared object name directly instead.

Read as a whole, the section says: this is a pre-one library whose soname moves with features, on a build system that does not give you the usual helper. Anyone packaging it should read this section before anything else, because it is the part with consequences.

Four files ship, and only one of them is the library

The names an installation produces are documented one by one, which is more than most C++ projects do, and the distinctions matter.

The real binary is a shared library whose filename carries three numbers: the major, minor and patch interface versions.

Then a soft link carrying two numbers, which is the shared object name proper. This is what other programs and libraries reference internally, and the documentation says you should never need to reference it directly in your build environment.

Then a soft link with no numbers at all, pointing at the highest major interface version available. This is the linker name, and it is what goes on the linker command line.

And a static archive. That one has no version in its filename, and the reason given is that when you link statically, all the symbols are resolved before the program runs, so there is nothing for an interface version to protect.

Three names, one library, and one rule about which one your build system should mention. If you have seen a build fail because a soft link was missing, this is the section that explains it.

Change the interface and you bump a file and a date

The contribution rule for versioning is spelled out, including the consequence of ignoring it.

The major version is incremented for incompatible interface changes, the minor for backwards compatible functionality, and the patch for backwards compatible fixes. You do that by editing one version file in the repository root, and the instruction is to always update the commit date recorded in that same file.

The reason is stated without hedging: if a contribution modifies the interface and the numbers are not updated, user applications and build environments will eventually break, because they will either try to link against the wrong version or, worse, link correctly and get undefined behaviour at runtime.

That second failure is the interesting one. A stale minor version does not produce a link error. It produces a program that starts, links, and then misbehaves, which is far more expensive to diagnose than a failed build. So the version file is not bookkeeping; it is the mechanism that turns an interface change into a visible failure.

There is a companion detail: the version file itself carries a licence sidecar, so it is covered by the project's licence compliance tooling like every other file.

Ten dependencies, two compression libraries, two build systems

The dependency list is short enough to read in one pass and tells you what the framework is made of.

There is the build system, the documentation generator and the test framework, which are tooling rather than runtime. Then the runtime set: a TLS library, a JSON parser, a date and time library, two compression libraries, one for brotli and one for zstandard, and an event loop library.

Two compression algorithms in a REST framework is a deliberate choice rather than an accident. It means the content encoding negotiation on the wire has two modern options rather than one, which matters if you are writing a server and a client in the same process.

Then the build systems. The project builds with Meson, complete with an options file and a subprojects directory for dependencies, and the tree also carries a CMake file. Both are supported, which is friendlier than picking one and is also twice the packaging work.

Licensing hygiene is handled with a dedicated directory for licence texts, a configuration directory for the SPDX reuse tooling, and a badge pointing at a service that reports the project's compliance. That is more machinery than most libraries carry for this, and it means the per-file licensing that the SPDX headers in the sources require is actually enforced.

Precompiled packages are the recommended path, and the matrix is explicit

The documentation tells you what to do first: if you do not need to change the source, use a precompiled package, because it will save you time. Then it delivers on that.

It is in the official Debian and Ubuntu repositories, from Debian 12 and Ubuntu 23.10 onwards, under one development package name. On macOS there is a package manager formula.

The architecture list is given as a plain enumeration: 64-bit x86, 64-bit arm, 32-bit arm hard-float, 32-bit x86, little-endian 64-bit PowerPC, riscv64, and s390x. And then the honest caveat, that as of writing there are no packages for any MIPS-related architecture that have been either built or tested.

That sentence does more work than it looks. Seven architectures tested and one family explicitly not tested tells you the project's real reach, which is servers and embedded boards rather than anything MIPS-shaped.

For Ubuntu there are two package archives: one carrying daily snapshots labelled unstable, and a stable one that receives release packages from time to time. Both have their own three-line install. The stable archive is three commands:

sh
$ sudo add-apt-repository ppa:pistache+team/stable
$ sudo apt update
$ sudo apt install libpistache-dev

And the last subsection of the README is an invitation for other distribution maintainers to insert their own instructions, which tells you which platforms the project does not yet cover with binaries.

The examples are small, and one of them shuts the server down

The example directory is eight files and is worth reading as a feature list, because each one is named after what it demonstrates.

There is the smallest possible server, a plain HTTP server, a plain HTTP client, a server that shuts down, a REST server, a REST example built around a description, and a custom header example. Plus a build file for the directory itself.

The shutdown example is the one that tells you something. A framework that cannot be stopped cleanly is a framework you cannot test, so shipping an example whose only purpose is to terminate the server is a statement about what the author considered necessary to show.

The client example matters for the same reason the framework exists in C++ at all: both ends of a connection can be in your process.

On maintenance, the picture is a set of releases titled for the same four platform families, all published within a fortnight in December 2024, with commits continuing into the middle of 2026. The build badges point at two workflow files, one for a Linux build and one that appears to run packaging tests, and the tree carries both a continuous integration config and a coverage config.

Editorial conclusion

Use Pistache if you are writing a C++ service and want a REST layer that does not drag a web framework's runtime into your build. It ships precompiled packages for the main Linux distributions and macOS, so the cost of adopting it is low, and its interface versioning is documented well enough to package safely. Skip it if you need complete API documentation today, because the project states plainly that it is still looking for a volunteer to write it and publishes only partial docs. Before you package it, read the versioning section and the four shipped file names, since that is the part that quietly breaks downstream builds when a contributor forgets it, and remember the framework is pre-1.0: the soname currently follows feature releases rather than being frozen to the major version.

Frequently asked questions

What is Pistache?

A modern HTTP and REST framework for C++, written entirely in pure C++17 and supporting Linux, macOS, Windows and FreeBSD, OpenBSD and NetBSD. Build instructions are supplied as separate text files per platform, and the project states that full API documentation is still being written by a volunteer.

How do I install Pistache?

From a precompiled package if you do not need to patch the source. It is in the official Debian and Ubuntu repositories from Debian 12 and Ubuntu 23.10 under one development package name, there is a package manager formula for macOS, and Ubuntu has separate daily snapshot and stable package archives.

How does Pistache version its library interface?

Separately from the release version, with the interface version carried in the shared library filename. A contribution that changes the interface must bump the major or minor version and update the commit date in the version file, or downstream applications will link against the wrong version or get undefined behaviour at runtime.

Why does Pistache set its shared object name directly?

Because it builds with Meson, and the GNU libtool abstraction that normally exports symbols portably is not supported there. The project sets the name directly instead, and documents the resulting three-name scheme.

Which architectures does Pistache support?

Seven are built and tested: 64-bit x86 and arm, 32-bit arm hard-float, 32-bit x86, little-endian 64-bit PowerPC, riscv64 and s390x. No packages for any MIPS-related architecture have been built or tested.

Official sources

  1. License: Apache-2.0
  2. pistacheio/pistache on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pistacheio-pistache.svg)](https://hysenlabs.com/projects/pistacheio-pistache)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pistacheio-pistache.svg)](https://hysenlabs.com/projects/pistacheio-pistache)

Was this useful?