Gravity Forms REST API v2 RC1 Released
By Steve Henty
Published August 8, 2017
The Gravity Forms REST API version 2.0-rc-1 is now available on the downloads page. This a developer-focused, feature plugin which contains version 2 of the current Web/REST API. It will soon be added to the Gravity Forms core so we encourage developers to give their feedback now.
The aim of version 2 is to dovetail with the WordPress REST API in terms of routing, discovery, authentication, usage, extensibility and best practices. It also provides the solid foundation we need for the development of future versions of Gravity Forms and add-ons.
Version 2 will work alongside version 1 but users will have the option to turn off version 1. Support for version 1 will be phased out so it’s very important that developers begin adding support for version 2 now.
Please send all your bug reports, questions and comments by opening a support ticket. The development version of the plugin can be found in the public repository on GitHub.
Upgrading to Version 2
The API is intended to feel as familiar as possible to developers who have worked with the WordPress REST API. The endpoints are largely the same as version 1, however, the responses are slightly different and authentication is no longer handled by Gravity Forms.
The following breaking changes are required by clients to consume version 2:
Content-Type
The API accepts both standard form fields and JSON content types. When sending JSON, the content-type request header must be set to “application/json”. If the content-type is omitted then the request will be interpreted as “application/x-www-form-urlencoded”.
No Response Envelope
The response will not be enveloped by default as in version 1. This means that the response will not be a JSON string containing the “status” and “response” – the body will contain the response and the HTTP code will contain the status code.
The WP-API will add an envelope to the response if the _envelope parameter is included in the request.
Authentication
Authentication is now no longer handled by Gravity Forms.
If you’re using cookie authentication, WordPress supports cookie authentication out of the box so you’ll just need
to change the way the nonce is created and sent. Create the nonce using wp_create_nonce( ‘wp_rest’ ) and send it
in the _wpnonce data parameter (either POST data or in the query for GET requests), or via the X-WP-Nonce header.
The signature authentication used in version 1 has been removed in version 2. If you’re using signature authentication then you’ll need to implement either Basic or OAuth authentication for the WordPress REST API. Further details here:
WordPress REST API authentication documentation
WP REST API: Setting Up and Using Basic Authentication
WP REST API: Setting Up and Using OAuth 1.0a Authentication
Form Submissions
The Form Submissions endpoint now accepts application/json, application/x-www-form-urlencoded and multipart/form-data content types. With the introduction of support for the multipart/form-data content type files can be sent to single file upload fields.
Request values should be sent all together instead of in separate elements for input_values, field_values, target_page and source_page.
Example body of a JSON form submission:
{
"input_1": "test",
"field_values" : "",
"source_page": 1,
"target_page": 0
}POST Single Resources
In order to maintain consistency with the WP API, the POST /entries and POST /forms endpoints no longer accept collections. This means that it’s no longer possible to create multiple entries or forms in a single request.
For further technical details, check out the readme.md file in the plugin folder.
REST API Add-On v2.0 Changelog
- Added the Location header when the confirmation is a redirect.
- Added sanitization to the /forms endpoint.
- Added the POST /entries/<entry-id>/notifications endpoint which (re)sends notifications.
- Added the _fields query param to the GET /entries, GET /entries/<entry-id> and GET /forms/<form-id>/entries endpoints.
- Added the include query param to the GET /entries.
- Fixed the status code for invalid submissions.
- Changed the ‘labels’ query param to ‘_labels’ to match WP API properties.
- Removed the GET /entries/<entry-id>/fields/ and GET /entries/<entry-id>/fields/<field-ids> endpoints.
- Removed support for semicolon separated entry IDs in the GET /entries endpoint. Use the include query param instead.