Get Form Information

GET /forms

Enables the retrieval of form meta data based upon the query parameters given. This end-point provides a way to synchronize the form information with the canonical source (Combo database at The IDEA Center). This provides access to form names, versions, and types.

Resource URL

https://api.ideasystem.org/v1/forms

Parameters

page
optional
Default: 0
Example: /v1/forms?page=1
Used to retrieve more results. Can be incremented until the results returned are less than the max parameter.
max
optional
Default: 50
Example: /v1/forms?max=10
The max parameter can be used to limit how many results are returned. It is recommended that this value be set as low as possible given the client needs. The max allowable value is 100. If a value greater than 100 is specified, only 100 results will be returned.
name
optional
 
Example: /v1/forms?name=Chair
Filters forms based upon the name given. This will be treated as a fragment and use it to find forms that contain the given name.
type
optional
 
Example: /v1/forms?type=Information
Filters forms based upon the type given. This can be "Information" or "Response".
version
optional
 
Example: /v1/forms?version=2.1
Filters forms based upon the version given.
current
optional
Default: true
Example: /v1/forms?current=true
Filter the forms that have the matching current value. For example, if you want only those that are currently in use, set current to true.
include_question_groups
optional
Default: false
Example: /v1/forms?include_question_groups=true
Include a list of the standard IDEA question groups associated with each form type.

Response

The return will be an HTTP 200 along with JSON if the request is valid. It should return a list of forms that match the given criteria.

If there is an issue with the backend, a HTTP 500 (Internal Server Error) is returned. If an error occurs with invalid parameters (e.g, using a String when a boolean is expected), an HTTP 400 (Bad Request) is returned.

Response Parameters (JSON Body)

max
Example: "max": 50
Shows the maximum number of responses.
page
Example: "page": 1
Shows the page number.
total_results
Example: "total_results": 143
Shows the total number of results that are provided by the given query.
data
Example: "data": { ... }
An array of form objects will be returned in this section. The size of this array should match the total_results.
data.id
Example: "id": 324
The unique identifier of this form. This is used in other REST end-points to query and submit data.
data.name
Example: "name": "Chair"
The name of this form (human readable). For example, Chair, Admin, or Diagnostic, Advisor, Advising Staff, Advising Student.
data.format
Example: "format": "Online"
Defines if this is Online or Paper. Unless you know otherwise, it is always best to only use forms that use the Online format.
data.type
Example: "type": "Information
Defines if this is an Information or Rater form.
data.version
Example: "version": "2.1"
Defines the version of this form.
data.current
Example: "current": true
Defines if this form is the most current version. Unless you know otherwise, it is always best to only use forms that are current ("current": true)

Example

This request will get all the Chair related forms that are current.

Request URL

GET /v1/forms?current=true&name=Chair

Response (as JSON)

HTTP 200
{
"max": 10,
"page": 0,
"total_results": 2,
"data": [
    {
        "id": 13,
        "name": "Chair",
        "format": "Online",
        "type": "Information",
        "version": "2.6",
        "current": true
    },
    {
        "id": 14,
        "name": "Chair",
        "format": "Online",
        "type": "Response",
        "version": "2.6",
        "current": true
    }]
}