API request and response format

[markboots]

Goal: develop the endpoints, format, parameters, and data flow of API access via the Flow Results spec.

System Roles: (Platforms can play multiple roles)

• Data Collector: e.g.: InSTEDD or VOTO or RapidPro, or a mobile device
• Data Aggregator: e.g.: Ona
• Data Consumer: e.g.: U-Report

Actions

"Publish": A Data Collector sends new data to a Data Aggregator

POST /flow-results/packages [creates/defines a new package]

• Parameters
  • descriptor_file with or without uuid (Descriptor Can be posted with uuid, or without and have Data Aggregator assign it)

POST /flow-results/packages/[uuid]/responses

• JSON post in the body, of the "Responses" json array. One row in the array, or many.
• Append-only semantics (not changing old responses, but adding new ones)
• Note: the Row ID can be (must be?) null for new data (TODO: What happens if it's provided? The Aggregator might need to define/assign it's own row IDs)

"Retrieve": A Data Consumer or another Aggregator requests data (full or paginated) from a Data Aggregator

GET /flow-results/packages - list of flow-results packages

GET /flow-results/packages/[uuid] - get the descriptor for one package

GET /flow-results/packages/[uuid]/responses - Get the data for a package

• pagination and page size parameters based on JSONApi
• filters:
  • max-version: timestamp of flow modified: only include responses recorded to flows up to this version (Do we also want min-version?)
  • start-timestamp: earliest response to fetch (inclusive)
  • end-timestamp: last response to fetch (exclusive)

[markboots]

Authentication options

• Basic (HTTPS only)
• Permanent Token (HTTPS only)
• Time-bound (session) Token (HTTPS only)
• JWT
• Oauth2
• Digest

HEAD /flow-results/[packages|uuid/responses] for digest authentication and or Temp/Session Token

[markboots]

Suggestions on the call:

• Endpoints that need authentication must support token-based in header : Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42
• Endpoints that need authentication are recommended to support HTTPS Basic Auth
• Issuance of tokens is outside the scope of the spec; we recommend Oauth2 but leave that outside this spec

[markboots]

Do we want to use jsonapi.org for the structure of responses?

[markboots]

• Should it also be used for the response of the data section as well? This would wrap our original spec:

[
  [ "2017-05-23T13:35:37.356-04:00", 20394823948, 923842093, "ae54d3", "female", {"option_order": ["male","female"]} ],
  [ "2017-05-23T13:35:47.012-04:00", 20394823950, 923842093, "ae54d7", "chocolate", {} ],
  [ "2017-05-24T15:15:37.981-04:00", 20394823952, 923842086, "ae54d3", "male", {"option_order": ["male","female"]} ],
  [ "2017-05-23T15:16:12.005-04:00", 20394823953, 923842086, "ae54d7", "vanilla", {} ],
  [ "2017-05-23T15:16:20.781-04:00", 20394823954, 923842086, "ae54d8", 196, {} ],
  [ "2017-05-23T15:16:38.119-04:00", 20394823955, 923842086, "ae54da", "I am feeling curious.", {"type": "text", "language": "eng"} ],
  [ "2017-05-23T17:25:12.722-04:00", 20394823956, 923842093, "ae54da", "https://myexampleflowserver.org/resources/audio/20394823956.ogg", {"type": "audio", "language": "eng", "format": "audio/ogg"} ],
  [ "2017-05-23T17:25:47-04:00", 20394823957, 923842093, "ae54db", "[35.678323, -108.25343]", {} ]
]

In a richer JSON object that included the pagination links, like:

{
  "data": {
    "type": "flow-results-data",
    "id": "[package id]",
    "attributes": {
      responses: [
  [ "2017-05-23T13:35:37.356-04:00", 20394823948, 923842093, "ae54d3", "female", {"option_order": ["male","female"]} ],
  [ "2017-05-23T13:35:47.012-04:00", 20394823950, 923842093, "ae54d7", "chocolate", {} ],
  [ "2017-05-24T15:15:37.981-04:00", 20394823952, 923842086, "ae54d3", "male", {"option_order": ["male","female"]} ],
  [ "2017-05-23T15:16:12.005-04:00", 20394823953, 923842086, "ae54d7", "vanilla", {} ],
  [ "2017-05-23T15:16:20.781-04:00", 20394823954, 923842086, "ae54d8", 196, {} ],
  [ "2017-05-23T15:16:38.119-04:00", 20394823955, 923842086, "ae54da", "I am feeling curious.", {"type": "text", "language": "eng"} ],
  [ "2017-05-23T17:25:12.722-04:00", 20394823956, 923842093, "ae54da", "https://myexampleflowserver.org/resources/audio/20394823956.ogg", {"type": "audio", "language": "eng", "format": "audio/ogg"} ],
  [ "2017-05-23T17:25:47-04:00", 20394823957, 923842093, "ae54db", "[35.678323, -108.25343]", {} ]
]
    },
   "relationships": {
      "descriptor": {
        "links": {
          "self": "http://example.com/flow-results/packages/[uuid]/",
        },
      },
    "links": {
      "self": "http://example.com/flow-results/packages/[uuid]/responses?page[cursor]=2348723948",
      "next": "http://example.com/flow-results/packages/[uuid]/responses?page[cursor]=2348724348",
      "previous": "http://example.com/flow-results/packages/[uuid]/responses?page[cursor]=2348723348"
    }
  }
}

[markboots]

Completed in PR https://github.com/FLOIP/flow-results/pull/19

[markboots]

Closing with PR #19 .