Mastercard's terraform-provider-restapi, a generic REST client for Terraform

A provider for APIs that have no provider of their own

The Mastercard terraform-provider-restapi exists to cover a specific gap: interacting with APIs that do not yet have a first-class Terraform provider. The implementation is described bluntly as a dumb REST API client, and the provider is characterised as a Terraform-wrapped cURL client with JSON support.

That framing sets expectations honestly, and it is also the key trade-off. Because the provider is generic, it cannot know anything about the semantics of the API in front of it. You have to know quite a lot about the API you are interacting with, in contrast to a full-featured provider written with one specific API in mind. The benefit is reach: any JSON REST API that satisfies a short list of requirements can be managed as code today rather than after somebody writes and maintains a dedicated provider for it.

The implementation is Go, built on the Terraform plugin framework and the plugin SDK, with a module path of github.com/Mastercard/terraform-provider-restapi and a Go version of 1.25.0 in go.mod. It also pulls in golang.org/x/oauth2, go-retryablehttp for retries, and evanphx/json-patch, all visible in the dependency list. The resource it exposes is restapi_object, with a matching restapi_object data source.

Four verbs, a unique id and JSON bodies, with no exceptions

The provider lists the requirements an API must meet, and they are worth reading as a contract before you write any configuration. The API is expected to support POST for creating an object, GET for reading one, PUT for updating one and DELETE for removing one. An object must have a unique identifier that the API returns. Objects live under a distinct path, so for a path like /api/v1/things, a POST on /api/v1/things creates a new object while GET, PUT and DELETE on /api/v1/things/{id} manage an existing one.

The third requirement is the one that rules out a lot of APIs. Request and response bodies must be JSON. The data field on restapi_object is parsed as JSON internally, and the body sent to the API is always JSON-encoded even if you change Content-Type to something else through the provider's headers map. APIs that require a different request body format, such as application/x-www-form-urlencoded or multipart, are not supported.

The failure mode for this is concrete. If the API does not accept JSON request bodies, a create or update comes back as HTTP 415 unsupported media type, and changing the Content-Type header does not help because the encoding is decided by the provider. When that happens, the documentation points you at modelling the resource differently rather than at tuning the request.

DELETE semantics decide whether destroy ever works

The provider issues DELETE on destroy by default, and it can be overridden per resource with destroy_method. The warning attached to that option is the most important operational detail in the whole README, because a failed destroy blocks applies.

If the API rejects DELETE for any reason, for example because deletion is disabled server side, the Terraform destroy step fails. That failure then blocks applies on any state change that triggers a recreate, so one resource with a broken delete can hold up a whole plan. The documented workaround is to set destroy_method to POST, or to any method the API does accept, together with a destroy_data body that the API treats as a no-op. The documentation is direct that this is a workaround and that the cleanest approach for DELETE-disabled APIs is to model the resource with null_resource plus local-exec instead.

That last point is a good summary of the provider's posture. It gives you the tools to force a destroy path through an API that does not want one, but the author prefers you fall back to a generic local-exec pattern when the API's semantics do not fit. A provider that can talk to almost anything is necessarily one where you remain responsible for understanding what you are pointing it at.

Maintenance mode and what it means for your plan

The project states its own status plainly in a maintenance note: this provider is largely feature-complete and in maintenance mode. The clarifying lines are worth quoting in spirit. It is not dead, it is just slow moving, and updates must be done very carefully. Code updates happen sporadically throughout the year, driven primarily by security fixes and pull requests. The project encourages community participation with open issues for usage and welcomes pull requests.

There is also an explicit limitation on support: because of the many API variations and the flexibility of this provider, detailed per-API troubleshooting cannot be guaranteed. That is the line that should shape an adoption decision. You are not going to get help debugging how your particular API behaves.

The release history backs the picture. Version 3.0.0 was tagged on 2026-02-27, preceded by v3.0.0-rc1 on 2026-01-14 and v3.0.0-rc2 on 2026-01-28, and the last push to the repository was on 2026-09-23. So the 3.x line is settled and the code is still receiving occasional work, but a new major version is not going to arrive on a schedule. The licence field on the repository says Apache-2.0, which is permissive enough for internal use without much fuss.

Debugging means reading the debug log yourself

Troubleshooting is where a generic provider differs most from a purpose-built one, and the documentation does not pretend otherwise. Because the provider is a Terraform-wrapped cURL, the API details and the Go implementation of the client leak into what you see, so troubleshooting lands partly on you.

The main tool is the debug log, enabled by setting the environment variable TF_LOG=1 and enabling the debug parameter on the provider. The guidance is to rely on it heavily and review the output when an unexpected error occurs, looking closely at the HTTP request details when the API returns an odd status code, which the documentation calls common for bad requests. Two environment variables matter in practice. TF_LOG=1 turns on the log, and API_DATA_IS_SENSITIVE=true hides the data the provider submits along with the data the API returns, which is off by default.

That second variable deserves attention in a provider that manages arbitrary API objects. By default the data is not considered sensitive, which is convenient until a payload contains a credential. Setting API_DATA_IS_SENSITIVE=true is the documented way to keep request and response bodies out of the log you are about to paste into a bug report.

The fakeserver cli for trying the client without an API

The repository ships a fakeserver cli tool, included in releases, and the documentation recommends playing with it to get a feel for how the API client is expected to work. There is also an examples directory with working use cases built against fakeserver, plus separate directories for data sources, provider, resources and working examples.

This is the part of the project that makes evaluation cheap. You can drive the provider against a fake service, see the exact requests it issues, and learn the request and response shapes without an account, a network path or a live API to pollute. For a provider whose troubleshooting burden falls on the user, a local target to experiment against is worth more than it looks.

The fakeserver lives in the fakeserver/ directory at the top level of the repository, alongside internal/ for the provider implementation, main.go as the entry point, docs/ for the generated provider documentation, and scripts/ and tools/ for release and docs generation. The Makefile shows the maintenance surface: fmt runs gofmt, test runs the Go test suite with coverage, test-race runs it under the race detector, testacc runs the acceptance tests with TF_ACC=1, and build compiles the module.

Alternatives and when a data source is the better fit

The provider documents its own alternatives, which is unusual and useful. The community has recommended three other providers in issue discussions. hashicorp/http is a data source provider that can make a request and give raw access to the response headers and payload. salrashid123/http-full extends the data source capabilities of hashicorp/http with additional verbs and proxying. magodo/restful offers similar capabilities with additional support for JSON PATCH, which is the RFC6902 patch format.

The difference in approach is the important part. This provider manages objects: it creates, reads, updates and deletes them, and it keeps Terraform state in step with a remote API. The data source providers make a request and expose the result, which means they fit a pipeline that reads from an API and feeds values into other resources, but they do not manage the lifecycle of a remote object. JSON PATCH support is the other axis, and it is the specific gap to check first, because a partial update expressed as a patch is not something a PUT-based generic client does.

The choice, then, comes down to what you need the API for. If you want Terraform to own the lifecycle of objects in that API and the API meets the four requirements above, this provider does that job. If you only need to read from an API, or you need patch semantics, one of the listed alternatives is a better fit.

Editorial conclusion

terraform-provider-restapi suits platform engineers who need to bring a small internal JSON API under Terraform before a dedicated provider exists, and it does not suit teams that need form-encoded bodies, JSON PATCH, or an API they cannot inspect with a debug log. Before you adopt it, check that the API accepts DELETE on every resource and returns a stable unique id, read the destroy_method and destroy_data options if deletion is disabled, and confirm the provider version you pin is the one whose behaviour you have read about, since the project describes itself as largely feature-complete and in maintenance mode.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Mastercard/terraform-provider-restapi on GitHub
4. README
5. Releases