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

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, overwrites all fields

PATCH

Used for partial updates to an existing resource

DELETE

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

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

405 Method Not Allowed

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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-list/curl-request.adoc[]

or

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-list/http-request.adoc[]

Example response

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-list/http-response.adoc[]

Response structure

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-by-id/curl-request.adoc[]

Example response

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-by-id/http-response.adoc[]

Response structure

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-by-last_modified_gt/curl-request.adoc[]

Example response

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-by-id/http-response.adoc[]

Response structure

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-post/request-fields.adoc[]

Example request

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/surveys-post/curl-request.adoc[]

Example response

Unresolved directive in resources/surveys.adoc - include::/home/travis/build/FundacionParaguaya/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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-list/curl-request.adoc[]

or

Unresolved directive in resources/snapshots.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-list/http-request.adoc[]

Example response

Unresolved directive in resources/snapshots.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-list/http-response.adoc[]

Response structure

Unresolved directive in resources/snapshots.adoc - include::/home/travis/build/FundacionParaguaya/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/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-post/request-fields.adoc[]

Example request

Unresolved directive in resources/snapshots.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-post/curl-request.adoc[]

Example response

Unresolved directive in resources/snapshots.adoc - include::/home/travis/build/FundacionParaguaya/stoplight-server/target/snippets/snapshots-post/http-response.adoc[]