Introduction

Form.IO has a built-in set of APIs that can be used to interact with the system. It also has a dynamically generated API that gets built when defining resources and forms.

This article assumes you have the following requirements met:

  • A local copy of the source code from https://github.com/formio/formio
  • You have a local MongoDB instance running and you have changed the MongoDB config in the default.json file to point to the DB instance
  • You have the code up and running at the URI: http://localhost:3001
  • You have setup the Admin username and password
  • You have Postman or curl available to query the API

API Endpoints

There are several API endpoints available in Form.IO. From my perspective there are 3 main types:

  • System management APIs like authentication and user management
  • Resource management APIs
  • Form management APIs

For each resource and form, you create in the UI, 5 API endpoints are generated. These are:

  • GET /<form or resource name>/submission
  • POST /<form or resource name>/submission
  • GET /<form or resource name>/{Id}
  • PUT /<form or resource name>/{Id}
  • DELETE /<form or resource name>/{Id}

The first time you start up the API there are 4 sets of endpoints already defined. Two sets for the two existing forms as well as an additional two sets for the two resources.
DefaultAPI

If you scratch around in the source code, you will notice that there is a swagger specification endpoint here: http://localhost:3001/spec.json?x-jwt-token=
In order to access the spec.json document you will have to first authenticate via the API and get a valid JWT token.

API Authentication JWT Token

In order to get a valid API token you need the following request:

URI: http://localhost:3001/user/login
Type: POST
Body of request:

{
    "data": {
        "email": "<Your configured admin user email>",
        "password": "<Password>"
    }
}

On successfull execution you will recieve a response with a custom header called x-jwt-token. The value of that header can be used for future authentication requests.
AuthenticationPost

API Authentication Pre-shared key

There is an additional method to authenticate using a shared key. This mechanism is reserved for a machine to machine communication. It should not be used via a browser. To create a shared key, set an environmental variable called API_KEYS with a comma-delimited string of keys. On windows, this method will not work. I use the bash console in VS code. Change the directory to the git repository folder.
Execute the following command to set an environmental variable with 3 keys.

export API_KEYS=0cc175b9c0f1b6a831c399e269772661,92eb5ffee6ae2fec3ad71c777531578f,4a8a08f09d37b73795649038408b5f33

To check the variable has been set you can run the command:

echo $API_KEYS

Now you can execute

npm start

If you open postman and execute the following endpoint:
URI: http://localhost:3001/spec.json
Type: GET
Header: x-token with a value of one of the API_Keys, i.e 4a8a08f09d37b73795649038408b5f33

You should see the swagger API document get retrieved. If you do not add the x-token with the value of one of the defined keys, you will get a 404 not authorized exception.

Get your swagger on

The spec.json provided by the API can be used to dynamically generate a usable API document. The only catch is, the spec document is a protected resource requiring authentication. The simplest way to get around this is to use one of the pre-shared API keys like this:

<!DOCTYPE html>
<html lang="en">
    
    <head>
        <meta charset="UTF-8">
        <title>Swagger UI</title>
        <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css">
    </head>

    <body>
        <div id="swagger-ui"></div>
        <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"> </script>
        <script type="text/javascript">
            window.onload = function () {
                // Swagger-ui configuration goes here.
                // See further: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
                SwaggerUIBundle({
                    deepLinking: true,
                    dom_id: '#swagger-ui',
                    showExtensions: true,
                    showCommonExtensions: true,
                    url: 'http://localhost:3001/spec.json', // <-- adjust this to your webserver's structure
                    requestInterceptor: (req) => {
                        debugger;
                            req.headers['x-token'] ='4a8a08f09d37b73795649038408b5f33';
                        
                        return req;
                    }
                });
            };
        </script>
    </body>

</html>

This will result in a document like below:
formioAPI

The problem with this is you cannot share this publicly as the API endpoints will have Administrative privileges. Meaning the caller could pretty much have free reign on your backend system. Also as already mentioned, you should not use the pre-shared keys from a browser. This can be used as a development aid on your dev machine.

Summary

In this article, we had a look at some of the API endpoints. We saw how to authenticate and how to get to the JSON spec document used to generate a Swagger UI.

If anyone is interested in how to do this on a publicly accessible address, let me know in the comments.

[<= HOME](https://therelentlessdev.com/form-io-with-asp-nte/)
*[TODO: NEXT =>]*