Summary of a discussion Gabe and I've had around happo

happo_api_endpoints.md

Report format:

[{
  component: 'Button', // The name of the component
  variant: 'default', // e.g. 'blue', 'with overflow', 'large', 'without user profile'
  target: 'android', // the combination of platform and viewport. For web, this will be 'firefox-mobile', 'firefox-desktop', 'chrome-desktop', etc. 
  width: 88, // the width of the image, not the viewport
  height: 30, // the height of the image, not the viewport
  url: 'http://img.png',
}]

On the backend, a combination of component, variant and target is used to uniquely identify a snapshot.

The endpoints you'd work with are:

To upload reports:
POST https://happo.now.sh/api/reports/:sha with body:
{
  snaps: [<an array of snaps>], // the report format described earlier
}
(returns a 20x response if things didn't go south)

To get report for a sha:
GET https://happo.now.sh/api/reports/:sha
(returns a 200 with the report if there is one)

Url to the diff page:
https://happo.now.sh/compare?q=<sha>..<other-sha>

Url to the compare endpoint: 
GET https://happo.now.sh/api/reports/<sha>/compare/<other-sha>
that returns a JSON object: 
{ equal: <true|false>, summary: '<a human-friendly text summarizing the result>', counts: <an object with a few numbers> } 
You can use the `equal` boolean to decide what to do next (post comment on PR). 

Authentication

All these endpoints are auth protected. The compare page will ask you for a google login, and the API endpoints use JWT (JSON web tokens). Have a look at the makeRequest function in the happo.io repo for more context on how to generate and use a token. You'll need an apiKey and an apiSecret for that. To get one, follow these steps:

1. Go to https://happo.now.sh/login
2. On successful login (you just land on the start page), go to https://happo.now.sh/api/me
3. Copy the apiKey and apiSecret from the json response.

(This will be handled through a UI at some point in the future).