Introducing the API Builder Package

We are thrilled to announce the arrival of the Convoworks API Builder Package, a powerful toolset designed to revolutionize the way APIs are developed for WordPress websites.

The API Builder Package is an all-encompassing solution that brings simplicity, speed, and flexibility to the complex task of API creation. With this package, you can easily define API routes and manage endpoint responses, all within an intuitive, user-friendly no-code interface.

To demonstrate the capabilities of the API Builder Package, we’ve attached a sample Convoworks service where you can find examples of all possible use cases that an API should support. We also provide an attached Postman collection and environment, which you can use for quick testing.

API Builder Examples (JSON)
Postman Collection (JSON) Postman Environment (JSON)

Example Service Configuration

Create a new Convoworks service, with the “Import from file” option selected. Enter the service name and upload the service definition “API Builder Examples” from the link above. Navigate to the Configuration view and enable the “API Builder” platform. To find the base url which is used for your custom API, navigate to the “Releases” view. Click on the “LINK” button to copy the base url to the clipboard. If you paste that url into your browser, you should see a JSON response with the message “Hello!”.

To test it with Postman, import the attached collection and environment (links above). In your environment, enter the copied base url into the “base_url” variable. Now, you can test all the example endpoints through Postman.

Examples in the Test Service

When you open the service in the Editor view, you will see the “Api Handler” step selected. All API calls for this service will be routed to this step. Here we have several processors, which compete to handle the request. The actual route matching is delegated to their Filter components (API Route Filter in this case). When the filter matches the request, elements in the processor’s OK flow are executed. Please note that in the following examples, we just used data from the request and returned some of it in the response. The goal of this article is just to introduce how to read data from the request. You can use that data with all other packages and components, like WordPress specialized components, forms package, etc. Although the components in the workflow are quite self-explanatory, let’s briefly explain a few notable ones.

Basic GET requests

Last two processors are handling simple GET requests. Empty route will activate when the service base url is requested. The base url can be obtained on the Releases view (if you enabled API Builder platform).
The “GET path variable and query parameters” demonstrates how you can define path, access eventual path variables, request query parameters and request headers. Path variables are accessed using the “result” object because hey are defined with a filter. This processor also demonstrates usage of the PSR-7 request we are using in Convoworks. Both calls can be executed with your browser, because they use GET method and are not requiring authentication.

How about WordPress authenticated requests?

With the API Builder package you can create custom API to support own frontend. In such case requests will contain X-Wp-Nonce header, meaning that you should be able to access user information if they are currently logged in. “Get user info” processor uses the wp_get_current_user() function to access user information, otherwise, when user is not logged in, it returns 401 response. This way are able to develop user aware API’s for your own front-end JavaScript widgets.

You can test this request using Postman. While you are logged in into your WordPress website, open developer console and grab the X-Wp-Nonce and Cookie values and enter into your Postman request. Endpoint should return user data.

For more WordPress functions you can access, check in the WP Core documentation, while available PHP functions are listed here.

Post, with JSON body, with files

POST examples are moved into a separate fragment with a purpose to demonstrate how you can group similar handlers and help yourselves when you have to create more complex API. The “POST Examples” fragment contains two processors, one handling request body data, while other combining it with uploaded files. Both features are accessed through a PSR-7 request.

Return 404 for non matched request

If no filter matched the request, Convoworks will execute Failback flow, which in this case will be perfect place to define not found (404) response.

Conculsion

Creating webhooks to receive 3rd party services data, creating API to support mobile applications, or just simply mocking the dummy API to be able to properly test your solution, those are usually things that require coding, which automatically corelates to larger expanses. With Convoworks API builder, that task can now be handled by almost anyone and you don’t need a FTP for it!