PHPackages                             calderawp/rest-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. calderawp/rest-api

ActiveLibrary[Utility & Helpers](/categories/utility)

calderawp/rest-api
==================

A boilerplate for new composer based PHP projects.

0.2.0(7y ago)040GPL-2.0PHPPHP ^7.2

Since Jan 9Pushed 7y ago2 watchersCompare

[ Source](https://github.com/CalderaWP/rest-api)[ Packagist](https://packagist.org/packages/calderawp/rest-api)[ RSS](/packages/calderawp-rest-api/feed)WikiDiscussions master Synced 4d ago

READMEChangelogDependencies (7)Versions (4)Used By (0)

Caldera REST API
================

[](#caldera-rest-api)

This is the forms package of the [Caldera Framework](https://github.com/CalderaWP/caldera) and provides REST API functionality to the framework.

This Is Not Caldera Forms.
--------------------------

[](#this-is-not-caldera-forms)

- Documentation for the [Caldera Forms REST API](https://calderaforms.com/doc/caldera-forms-rest-api/) for Caldera Forms 1.x.
- [Caldera Forms on Github](http://github.com/calderawp/caldera-forms/)
- [CalderaForms.com](http://calderaforms.com)

Overview
--------

[](#overview)

This package is primarily responsible for:

- Objects that describe:
    - REST API requests
    - REST API responses
    - REST API endpoints
    - REST API routes
    - REST API controllers
- Converting Exceptions to REST API responses
- The forms REST API (this may get moved to forms package)
    - CRUD via REST for forms
        - only read (GET) is implemented.
    - CRUD via REST for form entries
        - Read (GET) and write (POST) are implemented.

It is important to note that this package does not provide for form processing, or entry saving. This package should be a router only. It dispatches a serious of events - via the `CalderaHttp` module. Those events are used to

- The forms package subscribes to those events to provide entries or forms as needed.
- The forms package subscribes to those events to provide form processors
- The WordPress plugin subscribes to those events to provide database CRUD

The Request and Response objects extend objects from the Http package. You should probably read that package's README before completing this README.

Usage
-----

[](#usage)

### Install

[](#install)

- Add to your package:
    - `composer require calderawp/caldera-rest-api`
- Install for development:
    - `git clone git@github.com:CalderaWP/caldera-rest-api.git && composer install`

### Overview

[](#overview-1)

Main module class methods:

- `getCalderaEvents(): CalderaEvents` - Short cut to get the event module instance from container.
- `addRoute(RouteContract $route): CalderaRestApiContract` Registers routes
- `getRoute(string $className): RouteContract` - Get registered routes.

To add a route, you create one or more endpoints, add them to a route and then register the route with the module class's `addRoute()` method. This is explained in more detail below.

### Using

[](#using)

- Access from main container:

```
$http = \caldera()->getRestApi();
```

### Defining An Endpoint

[](#defining-an-endpoint)

Endpoints MUST implement the `calderawp\interop\Contracts\Rest\Endpoint` interface. This module has a `Endpoint` abstract class that provides most of the required methods. It is recommended to extend that class when creating an endpoint.

An endpoint represents a single entry point for the REST API. The endpoint class defines the endpoints rules and routes the request to wherever the business logic of the request lives -- probably the route.

When extending `Endpoint`, you have to add three methods to concrete class:

- `getArgs() : array` - The request arguments - same schema as a WordPress REST API endpoint -- or it should be :)
    - See:
- `handleRequest(Request $request): Response` - Process request.
    - Given a Request object, produce a Response object or throw an exception to indicate an error/ invalid request.
    - Do not do business logic here, dispatch to a reusable function.
    - In your endpoint unit tests, mock the functions that it calls, and ensure they get called.
- `getUri(): string` The URI for the endpoint
    - Example: `/forms`
- `authorizeRequest(Request $request): bool` Return true or false to indicate authorization.
    - NOTE: Try not to roll a custom authentication here, use one of the authentication traits.
    - NOTE: The authentication traits don't exist yet, return true for now.
- `public function getHttpMethod(): string` - The HTTP method `GET`, `POST`, etc.

### Defining A Route

[](#defining-a-route)

Endpoints MUST implement the `calderawp\caldera\restApi\Contracts` interface. This module has a `Route` abstract class that provides most of the required methods. It is recommended to extend that class when creating aroute.

An route represents a group of endpoints with the same base URL -- `/forms` and `/forms/` -- are endpoints of the same route.

When extending `Route`, you have to add three methods to concrete class:

- Nothing?

Routes MUST have an `addEndpoint(Endpoint $endpoint): Route` method. You can use this to add one or more endpoints to your route:

```
$route->addEndpoint( $endpoint );
```

#### Make Your Route Do Something

[](#make-your-route-do-something)

The `handleRequest()` method of the endpoint, should send the request, when valid to your route. In your route, you can have business logic if its testable there. In the form API, I used another layer of abstraction -- a controller to make testing and reuse easier. That may or may not be too complex. When making your own endpoints, question if that extra layer of abstraction solves any actual problems.

### Connecting To The WordPress REST API

[](#connecting-to-the-wordpress-rest-api)

The WordPress plugin in mu-plugins has a trait that can be used to register these endpoint/ routes with WordPress. The README for that plugin explains more.

### Using With A Standards-Friendly PHP Framework

[](#using-with-a-standards-friendly-php-framework)

The `calderawp/http` package already has conversion from Caldera HTTP request/responses and PSR-7 request/responses. So it should not be hard to use this REST API with a PHP framework such as Slim. I fully intend to make a trait like the one I did in WordPress to handle that logic.

### Making A Remote HTTP Request From An Endpoint Callback

[](#making-a-remote-http-request-from-an-endpoint-callback)

It is not uncommon for a REST API route to act as a proxy for a 3rd-party API. For example, a request to a Caldera endpoint might cause the system to find Stripe credentials, use them to query the Stripe API and then return formatted results to the client. In this case an HTTP request must be made on the server. This request MUST be made using the `calderawp/http` package. See that package's README for more info.

### Sending Responses

[](#sending-responses)

WordPress JWT Authentication
----------------------------

[](#wordpress-jwt-authentication)

[See](./src/Authentication/README.MD)

Testing
-------

[](#testing)

- Run all tests (JK, just unit tests beacuse that's the pattern)
    - `composer test`
- Run unit tests
    - `composer test:unit`
- Run acceptance tests
    - `composer test:acceptance`

License, Copyright, etc.
------------------------

[](#license-copyright-etc)

Copyright 2018+ CalderaWP LLC and licensed under the terms of the GNU GPL license. Please share with your neighbor.

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity8

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~51 days

Total

3

Last Release

2581d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ca938daf3f2a666cd32c7bdb6e30714da6fe0e6cd5012fe4864b18afae43fbcd?d=identicon)[Shelob9](/maintainers/Shelob9)

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/calderawp-rest-api/health.svg)

```
[![Health](https://phpackages.com/badges/calderawp-rest-api/health.svg)](https://phpackages.com/packages/calderawp-rest-api)
```

###  Alternatives

[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

728272.9k20](/packages/civicrm-civicrm-core)[firefly-iii/data-importer

Firefly III Data Import Tool.

7545.8k](/packages/firefly-iii-data-importer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)