README

A comprehensive API plugin for Craft CMS that provides both REST and GraphQL access to Formie forms and submissions data. This plugin enables external systems (like SAP) to retrieve form data through authenticated endpoints using their preferred API style.

⚠️ Beta Notice

This plugin is currently in active development and provided under the MIT License for testing purposes.

Licensing is subject to change. We are finalizing our licensing structure and some or all features may require a paid license when officially released on the Craft Plugin Store. Some plugins may remain free, others may offer free and Pro editions, or be fully commercial.

If you are using this plugin, please be aware that future versions may have different licensing terms.

Requirements

• Craft CMS 5.0 or greater
• PHP 8.2 or greater
• Formie 3.0 or greater

Overview

The Formie REST API plugin provides:

• REST API: Custom RESTful endpoints for forms and submissions
• GraphQL API: Full access to Formie's native GraphQL schema
• Dual Authentication: API key (REST) and token-based (GraphQL) authentication
• Flexible Querying: Simple REST calls or powerful GraphQL queries
• Complete Documentation: Examples for both API styles
• Test Endpoints: Development-friendly test endpoints

Quick Comparison: REST vs GraphQL

Installation

Via Composer

cd /path/to/project

composer require lindemannrock/craft-formie-rest-api

./craft plugin/install formie-rest-api

Using DDEV

cd /path/to/project

ddev composer require lindemannrock/craft-formie-rest-api

ddev craft plugin/install formie-rest-api

Via Control Panel

In the Control Panel, go to Settings → Plugins and click "Install" for Formie REST API.

Environment Configuration

Add API keys to your .env file:

# Primary API key with full access
FORMIE_API_KEY="your_primary_api_key_here"

# Limited access key (read forms only)
FORMIE_API_KEY_LIMITED="your_limited_api_key_here"

# Development test key (dev mode only)
FORMIE_API_KEY_TEST="your_test_api_key_here"

Authentication

REST API Authentication

Include API key in request headers:

curl -H "X-API-Key: your-api-key-here" https://yoursite.com/api/v1/formie/forms

GraphQL Authentication

Create a token in GraphQL → Tokens and use Bearer authentication:

curl -H "Authorization: Bearer YOUR_GRAPHQL_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ formieForm(handle: \"contact\") { title } }"}' \
     https://yoursite.com/api

REST API Endpoints

Production Endpoints

Test Endpoints (Development)

Example Usage

REST API Examples

# List all forms
curl -H "X-API-Key: your-api-key" \
     https://yoursite.com/api/v1/formie/forms

# Get specific form by handle
curl -H "X-API-Key: your-api-key" \
     https://yoursite.com/api/v1/formie/forms/contactForm

# Get form submissions
curl -H "X-API-Key: your-api-key" \
     "https://yoursite.com/api/v1/formie/submissions?form=contactForm&limit=10"

GraphQL Examples

See GRAPHQL_EXAMPLES.md for comprehensive GraphQL usage examples.

# Basic form query
curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ formieForm(handle: \"contact\") { id title fields { handle name } } }"}' \
     https://yoursite.com/api

API Documentation

• API_TEST_GUIDE.md - Complete REST API testing guide
• GRAPHQL_EXAMPLES.md - GraphQL query examples and patterns
• .env.example - Environment variable configuration

API Key Permissions

Security Features

• API key validation
• Rate limiting per key type
• IP address logging
• Request validation
• CORS support
• Development mode restrictions

Plugin Settings

Navigate to Settings → Plugins → Formie REST API for:

• Plugin information
• Available endpoints overview
• Documentation links

Support

• Documentation: https://github.com/LindemannRock/craft-formie-rest-api
• Issues: https://github.com/LindemannRock/craft-formie-rest-api/issues
• Email: support@lindemannrock.com

License

This plugin is licensed under the MIT License. See LICENSE for details.

Developed by LindemannRock

Built for use with Formie by Verbb