webmachine: REST semantics for Erlang applications

Why webmachine adds more than mochiweb

webmachine addresses a specific gap between HTTP transport handling and application behavior. Its README describes mochiweb as providing low-level HTTP syntax management and data transfer, while webmachine supplies an application layer with HTTP semantic awareness. That separation is useful when decisions such as whether a representation may be read, replaced, or returned with a particular status need to participate in application logic rather than being reduced to route dispatch.

The intended audience is Erlang developers building REST-based web applications. The project originated at Basho, the company associated with Riak, and was later placed in a new organization so the broader Erlang community could participate. That origin does not by itself prove suitability for a particular workload, but it does explain why the project is presented as a reusable HTTP application layer rather than as a general web server.

This is not a drop-in replacement for mochiweb based on the repository description. mochiweb handles the lower HTTP concerns, and webmachine connects those concerns to application behavior. Projects that need only basic request parsing and response generation may have less reason to add this additional layer.

The decision flow between HTTP and Erlang behavior

Based on the repository layout, webmachine is implemented as an Erlang application under `src/`, with public interfaces under `include/` and resources under `priv/`. The README does not expose the internal state machine, callback names, or request flow in detail, so those implementation specifics should not be inferred. Its documented position in the stack is still clear: HTTP syntax enters through mochiweb, webmachine evaluates the semantics of that request, and application behavior supplies the resource-specific result.

That architecture differs from a controller-centered design in which a route receives a parsed request and calls handlers directly. Here, the defining feature is the application layer's explicit awareness of HTTP semantics. The value of that choice depends on whether the service needs protocol decisions to remain visible and consistent across resources. It also introduces a learning burden because developers must understand webmachine's own model before writing ordinary application code.

The available documentation points users to the project wiki for a fuller explanation. It does not include examples here for authentication, conditional requests, content negotiation, persistence, or error representation. Those subjects are central to judging adoption, but the README does not establish how webmachine implements them.

Generating and starting the first Erlang service

The documented quick start uses a separate rebar3 template rather than asking the user to copy an application from the main repository. The following commands clone that template into rebar3's template directory and generate an application. Replace `your_app_here` only when choosing the actual application name.

$ mkdir -p ~/.config/rebar3/templates
$ git clone https://github.com/webmachine/webmachine-rebar3-template.git ~/.config/rebar3/templates
$ rebar3 new webmachine your_app_here

The clone fetches the template repository into the directory used by rebar3. The final command creates a new application based on the `webmachine` template.

The README then builds a release and opens its console:

$ cd your_app_here
$ rebar3 release
$ _build/default/rel/your_app_here/bin/your_app_here console

According to the README, after the generated application is started it is available at `http://localhost:8080`. This is a local quick-start address, not a documented production deployment recommendation. The documentation does not state how to change the port, bind to another interface, configure TLS, stop the service, or package it for a particular operating system. The wiki is the stated next source for those tasks.

Building, testing, and type checking webmachine

The repository is configured as a rebar3 project. For contributors, the documented combined workflow runs dependency updating, cleanup, compilation, EUnit tests, and Dialyzer through the Makefile:

make all

The `all` target first resolves `rebar3`. If a `rebar3` file exists in the current directory, the Makefile uses it. Otherwise, it looks for `rebar3` on `PATH`. If neither source is available, the target downloads the executable from the URL defined in the Makefile. The build then invokes `rebar3 do update, clean, compile, eunit, dialyzer`.

Developers can separate two checks:

rebar3 eunit
rebar3 dialyzer

The first command runs EUnit, while the second runs Dialyzer according to the README. These commands concern the webmachine repository itself. They should not be confused with the commands used to create and start a generated application.

The repository has no GitHub releases. That means the README provides no stable release tag or release archive to select, and the quick start does not prescribe a release version. Contributors working against `main` may therefore receive source without a release-based upgrade path documented by GitHub.

Choosing between webmachine and direct mochiweb use

The clearest alternative described by the repository is to use mochiweb directly for applications that only need its HTTP syntax and connection handling. That approach leaves the service responsible for composing parsing, routing, application behavior, and HTTP response decisions. It avoids introducing webmachine's application layer when the project does not need a separate model for HTTP semantics.

webmachine is the better fit when the team wants that semantic layer already positioned between mochiweb and application code. The README describes this as a way to connect HTTP handling to application behavior, which can help keep protocol-aware decisions out of low-level request plumbing. Whether it improves a given service still depends on the team's familiarity with the model and the design conventions required by the generated application.

The documentation is thinner than a buyer would normally want. It does not provide a feature matrix, migration guidance, callback reference, deployment example, or performance comparison in the README. It also does not state that webmachine handles authentication, authorization, database access, or background jobs. Those omissions prevent a broad claim that it is more capable than direct mochiweb development. The practical distinction is architectural: mochiweb manages HTTP syntax, while webmachine adds HTTP-aware application behavior.

Maintenance, upgrades, and Apache-2.0 implications

The repository is not archived, and its last push was on 2026-07-24. That is recent activity, but the repository has no GitHub releases, so there is no documented release cadence or named upgrade series. Consumers should not equate source-branch activity with a stable release policy.

The project is licensed under Apache-2.0. That identifier tells a prospective user which license text governs the repository, but it does not answer legal questions about a particular deployment. The `LICENSE` file is the appropriate source for the exact terms. The README does not document dependency license review, version compatibility, or a support policy.

Upgrade planning also has a practical gap. Because no releases are listed and the quick start does not pin a version, the documented path does not explain how an application generated from one template state should migrate to another. Teams should inspect `rebar.config`, `rebar.lock`, and the generated application before treating an upgrade as routine. The lock file is part of the repository, but the README does not prescribe how users should update or interpret it.

Editorial conclusion

Adopt webmachine when an Erlang team wants HTTP semantics modeled explicitly above mochiweb and is prepared to consult the wiki for application structure and operational details. Do not choose it as a self-contained framework starter if you require a documented production configuration or release process. Verify first that your team accepts the resource model, that its Erlang and rebar3 toolchain matches the service environment, and that the generated application starts correctly on port 8080.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. webmachine/webmachine on GitHub