Skip to content

Request and Response Structures

Requests

Web Service requests must conform to a basic structure which contains execution instructions, and passed-in parameters (optional). Example request follows:

{
    "componentDocumentName": "ws-test-service",
    "functionName": "sortParameters",
    "functionParameters": [9,5,7,2,1,8,6,4,3,0]
}
value required description
componentDocumentName true Name of Component Document containing the web service function
functionName true Name of the function being called in the web service
functionParameters false An array of parameters to pass to the function being called

Refer to the execute API documentation for examples on how to call a Web Service Component Function using curl. This can be found here Execute a Web Service Component Function

Responses

Web Service responses are determined by the function creator. It is recommended that the response be structured as a Javascript Object, to maintain consistency with the core web services provided by Formbird (ie. Create, Retrieve, Search, etc).

Following on from the "sortParameters" example request above, an example response follows:

{
    "parameters": [0,1,2,3,4,5,6,7,8,9]
}

By default, the data will be returned in the response as JSON and will have a status code of 200. These can be customized by the following properties under "responseData".

  • statusCode - This is a numeric HTTP status code that indicates the success or failure of a request. It follows the standard HTTP status code format, as defined in the HTTP/1.1 specification. You can refer to the Mozilla Developer Network's documentation on HTTP status codes for more information on the possible status codes and their meanings.

  • body: This is the payload data that you want to return in the response. By default, the data returned from the web service will be used as the response body. However, if the body property is defined within the responseData object, it will be used instead. The payload can be in any format.

  • contentType: This is a string that specifies the media type of the response payload. It follows the MIME media type format, as defined in the Multipurpose Internet Mail Extensions (MIME) specification. You can refer to the Mozilla Developer Network's documentation on common MIME types for more information on the different media types and their formats.

  • headers: This is an object that contains key-value pairs of HTTP headers that can be included in the response. HTTP headers are additional metadata that provide information about the response or request, such as authentication tokens, caching policies, and more.

This is an example of customized response and header that returns xml file:

{
    responseData: {
        statusCode: 200,
        body: "<document><name>test</name></document>",
        contentType: "text/xml",
        headers: {
            "header-test-key": "header-test-value"
        }
    }
}

Refer to the API documentation for information on the core web services provided by Formbird.