API Reference

Authentication

All API endpoints are auth protected. To successfully issue a command, you need to provide an authentication header with your request. There are two ways to authenticate. JWT authentication is more secure but can be a little tricky to set up. HTTP Basic authentication is a less secure alternative, but is a good option if you want a simpler setup.

Basic authentication

With Basic authentication, you provide an Authorization: Basic <token> header where the token is a base64 encoded string of your apiKey:apiSecret tokens.

JWT authentication

This auth token is a JSON web token generated based on your API key and API secret. Pass { key: <your API key> } as the payload of the JWT call and the API secret as the secret, and set a kid header equal to the API key. Pass the resulting token as a Authorization: Bearer <generated token> header in all API requests.

An example of how to construct the JWT token can be found in the source code for the happo.io client.

Endpoints

Here's a full list of API paths you can call. All endpoints speak JSON. Body params are sent as a JSON blob in the body of the request. Responses are sent as JSON in the body of the HTTP response.

Create report

POST /api/reports/:sha

Uploads a list of snapshots for a certain identifier (usually a commit sha). Note: If there is an existing report for the same sha, it will be overwritten as a result of calling this endpoint.

URL params

shaStringThe id of the report.

Body params

snapsArray<Snapshot>A list of snapshot objects associated with the report
projectString(optional) The identifying name of the project this report should belong to. If none is specified, the default project will be used.
linkString(optional) URL to the source of the report (e.g. PR URL).
messageString(optional) A short string describing the source of the report (e.g. PR title).

Response

jsonObjectAn object containing a url where the uploaded report can be accessed

Get report

GET /api/reports/:sha

Gets a list of snapshots for a certain identifier (usually a commit sha).

URL params

shaStringThe id of the report.

Query params

projectString(optional) The identifying name of the project this report belongs to. If none is specified, the default project will be assumed.

Response

jsonArray<Snapshot>A list of snapshots associated with this sha.

Compare two reports

POST /api/reports/:sha1/compare/:sha2

Compare reports and get useful information on the possible differences.

URL params

sha1StringThe id of the "before" report.
sha2StringThe id of the "after" report.

Body params

projectString(optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.
linkString(optional) URL to the source of the report (e.g. PR URL).
messageString(optional) A short string describing the source of the report (e.g. PR title).
authorString(optional) The email address for the author of the change.

Response

jsonComparisonAn object with useful properties describing the differences between the two reports.

Add component subscriptions

POST /api/subscriptions/:component

Add subscribers (email addresses) to a specific UI component. When a diff is found in a component, subscribers are notified with a link to the Happo report. Users can themselves unsubscribe manually. If you try adding an email address that has been unsubscribed by the user, it will be ignored and the user will continue to be unsubscribed.

URL params

componentStringThe name of a component. Should match component names that are in the reports.

Body params

emailAddressesArray<String>A list of email addresses to add as subscribers.

Remove component subscriptions

DELETE /api/subscriptions/:component

Remove subscribers for a specific UI component.

URL params

componentStringThe name of a component. Should match component names that are in the reports.

Body params

emailAddressesArray<String>A list of email addresses to remove subscriptions for.

Objects

These are the domain objects you can come across while communicating with the API.

Snapshot

An object describing a screenshot of a certain component variant

urlString URL of the screenshot image. It's important that the URL is deterministically generated based on the contents of the image. A hash function (like md5) is of good help here, so that two images that have the same bitmap content end up having the same URL. More about URL creation.
variantStringThe name of the variant (e.g. "disabled")
targetStringThe snapshot's target (e.g. "firefox", "iphone 7")
componentStringThe name of the component shown in the screenshot (e.g. "Button")
heightNumberThe pixel height of the screenshot image
widthNumberThe pixel width of the screenshot image

Comparison

An object with useful properties describing the differences between two reports.

diffsArray<Snapshot>A list of snapshots that are different
addedArray<Snapshot>Snapshots that have been added
deletedArray<Snapshot>Snapshots that have been removed
unchangedArray<Snapshot>A list of identical snapshots
summaryStringA summary of the results, with the most important information listed
equalBooleanTrue if the two reports are identical, false otherwise