Figure out what the /people/analytics endpoint will look like.

analytics_endpoint_discussion.md

Analytics Endpoint

I'd like to know your thoughts on which version of this endpoint will be better, and your thoughts on the general format of the response. Want to make sure we are all on board with how the meta section will look like.

For reference: PEEPS-1612

Version A - with next_page_id

Initial Request

GET /people/analytics?owner_id=WF&updated_since=2016-01-13T12:39:50Z

Response:

  {
    data: [
      { ... }, # account hash
      { ... }
    ],
    errors: {},
    meta: {
      next_page_id: "kajsdnkaj12345rtfdchbbusw37489qiksda~-aksjdn",
      total: 1000
    }
  }

Consequent Request:

Use the next_page_id from the last request as a query param on the next request

GET /people/analytics?owner_id=WF&next_page_id=kajsdnkaj12345rtfdchbbusw37489qiksda~-aksjdn

Response:

  {
    data: [
      { ... }, # account hash
      { ... }
    ],
    errors: {},
    meta: {
      next_page_id: "poiuytrewq129348reuw21qwqieh0", # when this is nil, this is the last page
      total: 1000
    }
  }

Version B - with next_page_url

Initial Request

GET /people/analytics?owner_id=WF&updated_since=2016-01-13T12:39:50Z

Response:

  {
    data: [
      { ... }, # account hash
      { ... }
    ],
    errors: {},
    meta: {
      next_page_url: "http://secure.westfield.io/v1/people/analytics?owner_id=WF&next_page_id=oiuy67890wiury",
      total: 1000
    }
  }

Consequent Request:

Use the next_page_url from the last response to get to the next page of results

GET http://secure.westfield.io/v1/people/analytics?owner_id=WF&next_page_id=oiuy67890wiury

Response:

  {
    data: [
      { ... }, # account hash
      { ... }
    ],
    errors: {},
    meta: {
      next_page_id: "http://secure.westfield.io/v1/people/analytics?owner_id=WF&next_page_id=oiuy67890wiury",, # when this is nil, this is the last page
      total: 1000
    }
  }

Click on "Revisions" tab and comment on a particular line, if desired. Thanks!

Revisions tab does not seem to allow comments.
next_page_url requires less processing by the client, and is more abstract, so I think that may be better.

Supplying an empty string rather than nil for the end sentinel value fits with our standards (https://wiki.westfieldlabs.com/pages/viewpage.action?spaceKey=WL&title=API+Standards+and+Governance#APIStandardsandGovernance-Non-existentoremptydataempty_data) and will cause fewer bugs. It is just as unique in this context as nil.

ah good point, will do empty string "" instead of nil. and I agree that next_page_url seems better for the client, so i think we should do that too.

I think next_page_id is more flexible, if less abstract.

Providing the complete URL makes a large assumption, which that all clients can use URLs directly.

This is not true of the SDKs, for example, which would have to parse the next_page_id out of the URL in order to make the next request.

from offline discussions, with John and Ashod, we've decided to go with next_page_query and only do the query string, like: ?owner_id=WF&next_page_id=1234