Overview

Using SureCloud’s REST API, you can retrieve both the values and structural information for your Sections.

To access any of the services on the API a User must be authenticated to the SureCloud Platform. Two methods are available for this and are explained here.

All available services require an Accept header of 'application/json' to be sent.

'Accept: application/json'

Within this guide, we’ll explore how to:

• Find the Section you are looking for
• Retrieve the data stored for the Section
• Modifying Responses on a Section
• Creating a new Section (from an insertable) with Responses

SureCloud's RESTful API also uses Swagger documentation to explain how to use the APIs and to try out many of the features. This documentation can be found at https://secure.surecloud.com/swaggerDocumentation 

Within this documentation you can find all available functions, request information, HTTP status explanations, model explanations and much more.

 

 

Forms API

SureCloud's Forms API can be used to retrieve Form data and information - including information about Sections. The Forms API can be used to retrieve the Section Key of interest to then be used to access that Section directly using this Sections API.

 

 

Retrieving data for a Section

To view the data stored on a given Section it is possible to go direct from the Form Data (using the Forms API) supplied HATEOAS link for the section data.

{
    "key": 123
    "title": "Section 123",
    "description": This is an example section in a form",
    "path": "/example",
    "templateKey": 10000
    "position": [1],
    "links": 
    [{
        "rel": "self",
        "href": "http://localhost:8080/restful/v1/sections/122219/data"
    }]
}

Alternatively use the Section Data end point with a HTTP GET request if the sectionKey is already known.

https://secure.surecloud.com/restful/v1/sections/<sectionKey>/data

You can get this resource directly using the API with a cURL

curl -X GET --header 'Accept: application/json;charset=UTF-8' 
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/sections/<sectionKey>/data'

Additionally you can use our Swagger documentation to “Try it out!”.

 

Result

Making a successful call to the Section Data end point will result in a Response Code of 200, and return a body containing the SectionResponses model.

This model will be a structural representation of the Section found within SureCloud and contain the value of each response.

At a high level the response will be similar to the below example:

{
    "key": 0,
    "description": "string",
    "identifier": "string",
    ...
    "responses": 
    [{
        "key": 0,
        "mandatory": true,
        "title": "string",
        "type": "REFERENCE",
         ...
        "value": { <JSON representation of the value and type> }
    }],
    "sections": 
    [{
        <sub sections>
    }]
}

Refer to the Swagger documentation for model property explanations.

 

 

Modifying Responses on a Section

Using the Section Data end point with a HTTP PATCH it is possible to update the Responses on a Section. The request requires passing the sectionKey, of the Section you wish to update, in the URL path and Section Data in the request body.

https://secure.surecloud.com/restful/v1/sections/<sectionKey>/data

This service allows for any number of Responses on the Section to be updated at the same time.

{
    "key": 123,
    "responses": 
    [{
        "key": 321,
        "value": { "value": "Example new Value", "type": "TEXT" }
     },
     {
        "key": 322,
        "value": { "value": "Another example new Value", "type": "TEXT" }
     },
     ...
    }]
}

This resource can be accessed directly using the API with a cURL command.

curl -X PATCH --header 'Accept: application/json;charset=UTF-8'
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/sections/<sectionKey>/data' 
--data '{"key": 0, "description": "string", "identifier": "string", "responses": [{ "key": 0, "mandatory": true, "title": "string", "type": "REFERENCE", ... "value": { <JSON representation of the value and type> } }], "sections": [{ <sub sections> }]}'

Additionally you can use our Swagger documentation to “Try it out!”.

 

 

Create new Section with Responses

Using the Section Data end point with a HTTP POST it is possible to create a new Section (from an existing insertable Section) and populate the Responses on this Section. The request requires passing the Section Data in the request body.

https://secure.surecloud.com/restful/v1/sections/data

The Section Key for the Section being copied from should be provided (the new Section will be inserted directly below the provided one). This service allows for any number of Responses on the Section to be set at the same time as the creation of the new Section.

{
    "key": 123,
    "responses": 
    [{
        "key": 321,
        "value": { "value": "Example new Value", "type": "TEXT" }
     },
     {
        "key": 322,
        "value": { "value": "Another example new Value", "type": "TEXT" }
     },
     ...
    }]
}

This resource can be accessed directly using the API with a cURL command.

curl -X POST --header 'Accept: application/json;charset=UTF-8'
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/sections/data' 
--data '{"key": 0, "description": "string", "identifier": "string", "responses": [{ "key": 0, "mandatory": true, "title": "string", "type": "REFERENCE", ... "value": { <JSON representation of the value and type> } }], "sections": [{ <sub sections> }]}'

Additionally you can use our Swagger documentation to “Try it out!”.

 

Useful links:

Forms API Overview

Components of a Form

API Authentication