Introduction
The Poverty Stoplight API is a RESTful web service that provides resources related to surveys creation.
HTTP verbs
The API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.
| Verb | Usage |
|---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, overwrites all fields |
|
Used for partial updates to an existing resource |
|
Used to delete an existing resource |
HTTP status codes
The API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. For example,
| Status code | Usage |
|---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
|
The type of request for this resource is not allowed. For example, some endpoints may be GET only. Trying a POST will return this message. |
For more status codes, see the w3 standard
Resources
Surveys
The surveys resource returns surveys for various inputs
List of Surveys
A `GET` request with no parameters will return a list of potential surveys
Example request
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-list/curl-request.adoc[]
or
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-list/http-request.adoc[]
Example response
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-list/http-response.adoc[]
Response structure
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-list/response-fields.adoc[]
Get by ID
A GET request with a path parameter of the id will return the survey with that id.
Example request
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-id/curl-request.adoc[]
Example response
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-id/http-response.adoc[]
Response structure
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-id/response-fields.adoc[]
Get by last_modified greater than
A GET request with a request parameter with the last modified date and time as ISO string (UTC timezone).
Example request
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-last_modified_gt/curl-request.adoc[]
Example response
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-id/http-response.adoc[]
Response structure
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-by-id/response-fields.adoc[]
Create a Survey Definition
A POST request will create new survey with it’s schema definition.
Request Fields
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-post/request-fields.adoc[]
Example request
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-post/curl-request.adoc[]
Example response
Unresolved directive in resources/surveys.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/surveys-post/http-response.adoc[]
Snapshots
The snapshots resource returns snapshots for various inputs.
A snapshot is an instance of a particular filled out survey.
List of Snapshots
A `GET` request with a survey parameter will return a list of snapshots for the that survey.
Example request
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-list/curl-request.adoc[]
or
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-list/http-request.adoc[]
Example response
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-list/http-response.adoc[]
Response structure
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-list/response-fields.adoc[]
Create a Snapshot
A POST request will create new snapshot for a particular survey.
A snapshot is a set of key/value pairs, where each key/value is defined in the survey schema definition.
Request Fields
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-post/request-fields.adoc[]
Example request
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-post/curl-request.adoc[]
Example response
Unresolved directive in resources/snapshots.adoc - include::/home/runner/work/stoplight-server/stoplight-server/target/snippets/snapshots-post/http-response.adoc[]