Pmitz / Developers
Add Pmitz to your application
Start with one feature you already have. Define who can use it and how much they can use, then connect the checks and usage reports in your backend.
Get started
- Choose your operating option. Use Pmitz SaaS from Terpomo Software, embed Pmitz in a Java application, or run a separate HTTP service yourself.
- Define one product feature and limit. Start with an existing action such as a download, reservation, API request, or saved item.
- Supply the correct context. Use the appropriate user, subscription, or directory-group identifier consistently.
- Connect the decision and usage path. Your backend checks the plan and limit, performs the action, and explicitly reports successful use.
- Test the complete application flow. Include limits, changes, failures, retries, and simultaneous requests.
Java 17+ is required for the Java implementation and a self-operated server. Java is the first official client; the remote service exposes a language-agnostic HTTP API.
Pmitz SaaS
Use the service address and access configuration provided by Terpomo Software for your subscription. Integrate the Pmitz calls in your backend; Terpomo handles the Pmitz service’s operation. Your application still supplies context, performs the business action, and reports successful use.
Self-operated installation
git clone https://github.com/terpomo-io/pmitz.git
cd pmitz
export PMITZ_API_KEY="$(openssl rand -hex 32)"
docker compose up -dStarts the remote Pmitz server and PostgreSQL from the published Compose setup. Requires Docker Compose, Git, and OpenSSL.
dependencies {
implementation 'io.terpomo.pmitz:pmitz-all:0.9.0'
implementation 'io.terpomo.pmitz:pmitz-core:0.9.0'
implementation 'io.terpomo.pmitz:pmitz-limits:0.9.0'
implementation 'io.terpomo.pmitz:pmitz-subscriptions:0.9.0'
}Add the Java aggregate dependency, then configure Pmitz's repositories and verifiers. Requires Java 17+.
<dependencies>
<dependency>
<groupId>io.terpomo.pmitz</groupId>
<artifactId>pmitz-all</artifactId>
<version>0.9.0</version>
</dependency>
<dependency>
<groupId>io.terpomo.pmitz</groupId>
<artifactId>pmitz-core</artifactId>
<version>0.9.0</version>
</dependency>
<dependency>
<groupId>io.terpomo.pmitz</groupId>
<artifactId>pmitz-limits</artifactId>
<version>0.9.0</version>
</dependency>
<dependency>
<groupId>io.terpomo.pmitz</groupId>
<artifactId>pmitz-subscriptions</artifactId>
<version>0.9.0</version>
</dependency>
</dependencies>Add the Java aggregate dependency, then configure Pmitz's repositories and verifiers. Requires Java 17+.
Remote
In remote mode, your application calls the Pmitz service. The standalone Spring Boot server owns the JDBC connection. The published Docker setup starts the server with PostgreSQL.
The Docker commands above use the repository’s Compose file, which includes both services. Keep your API key on the backend. Replace the development database settings with your deployment’s configuration before production use.
| Resource | What it contains |
|---|---|
| Docker guide | Published image, Compose setup, database and API-key configuration |
| Architecture guide | Embedded and remote-mode composition |
| Java remote client | Java interfaces over the HTTP API |
| Sample applications | A public-library application with a Java BFF and web UI |
Embedded
In embedded mode, Pmitz executes in the same Java process as your application. Configure the product repository, limit and subscription verifiers, and JDBC repositories using your own datasource.
The examples declare core, limits, and subscriptions explicitly so their API types are available at compile time with the published 0.9.0 artifacts. pmitz-all adds the combined usage tracker. For Java remote callers, add io.terpomo.pmitz:pmitz-remoteclient:0.9.0 instead of wiring local repositories.
A Spring Boot starter is also available when you want to embed the remote-server behavior in your own Spring Boot application.
Use the full Java setup in the user guide .
Define the product rules
This example defines a music application’s existing download feature, a 200-download monthly quota, and a Premium plan that includes it:
{
"productId": "music",
"features": [{
"featureId": "download",
"limits": [{
"type": "CalendarPeriodRateLimit",
"id": "monthly-downloads",
"quota": 200,
"periodicity": "MONTH"
}]
}],
"plans": [{
"planId": "premium",
"includedFeatures": ["download"]
}]
}
Use CountLimit for a counter such as occupied playlist slots. Use CalendarPeriodRateLimit for a quota aligned to a calendar period. The application must supply the intended customer or shared-family context.
For the remote server, submit the product definition to POST /products with the X-Api-Key header. Load definitions into the configured product repository for embedded use.
Connect check, use, and record
The order below is illustrative pseudocode, rather than runnable Pmitz API names:
decision = checkPlanAndLimit(context, feature, 1)
if decision.permitted:
if performFeatureSuccessfully():
recordUsage(context, feature, 1)
else:
declineUse()
The feature stays in your application. Pmitz receives the context and amount you report; it does not automatically detect actions, failed downloads, or deletions.
For example, with the remote server and a configured product, check a proposed additional unit:
curl -X POST \
http://localhost:8080/users/alice/limits-check/music/download \
-H "X-Api-Key: $PMITZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"monthly-downloads": 1}'
After the application action succeeds, report its usage:
curl -X POST \
http://localhost:8080/users/alice/usage/music/download \
-H "X-Api-Key: $PMITZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"units": {"monthly-downloads": 1}, "reduceUnits": false}'
These examples use an individual user. Use the subscription or directory-group endpoints and configured plan/status information when that is the context your product needs. Inspect returned feature status and remaining units; do not treat a check as a reservation.
Understand storage
The supplied JDBC repositories support PostgreSQL, MySQL, and SQL Server. Product definitions describe the configured rules; usage and subscription repositories store the relevant persisted state.
- Calendar usage: reports accumulate in a relevant period total. A later month has its own window.
- Capacity usage: application-reported creation and reduction can update an occupied count.
- Current decisions: the normal usage interfaces expose current status and remaining units.
- Historical analysis: retained period records can be queried at repository level, but the supplied records are not an immutable event journal or past-decision explanation service.
- Cleanup: deletion of expired records must be invoked under an explicit storage policy.
Recording strategies, rule resolution, and repository interfaces have extension points. A custom activity journal or counting method requires implementation and testing; it is not a shipped alternative merely because the extension interface exists.
Test before production
Evaluate simultaneous consumption, duplicate reports, retries, business-action failure, database errors, multiple instances, calendar boundaries, plan changes, and outages.
Repository transactions do not establish an atomic check/action/record transaction across your application. Decide how your integration handles a successful action followed by failed recording, and test that policy.
For the full list of evaluation situations and responsibility boundaries, see the product guide .
