API Reference

Happo exposes a public, REST-like, API that you can use to create or enhance custom integrations. The API resides at https://happo.io, and all endpoints use the /api namespace.

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

URL params

sha String The id of the report.

Body params

`snaps`	`Array<Snapshot>`	A list of snapshot objects associated with the report
`project`	`String`	(optional) The identifying name of the project this report should belong to. If none is specified, the default project will be used.
`link`	`String`	(optional) URL to the source of the report (e.g. PR URL).
`message`	`String`	(optional) A short string describing the source of the report (e.g. PR title).
`partial`	`Boolean`	(optional) Set this to true to amend the report instead of overwriting it. This is useful if you are running multiple processes for the same sha. Remember to call the Complete Report endpoint once you are done uploading all the partials, otherwise the report will never be fully constructed and useful.

Response

json ReportStatus An object containing a url where the uploaded report can be accessed

Get report

GET /api/reports/:sha

URL params

sha String The id of the report.

Query params

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

Response

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

Get report status

GET /api/reports/:sha/status

URL params

sha String The id of the report.

Query params

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

Response

json ReportStatus An object containing useful information about a report

Complete a report

POST /api/reports/:sha/complete

URL params

sha String The id of the report.

Body params

project String (optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

json ReportStatus An object containing useful information about a report

Compare two reports

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

URL params

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.

Body params

`project`	`String`	(optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.
`link`	`String`	(optional) URL to the source of the report (e.g. PR URL).
`message`	`String`	(optional) A short string describing the source of the report (e.g. PR title).
`notify`	`String`	(optional) An email address, or a list of comma-separated email addresses that you want to notify with the results of the comparison.
`isAsync`	`Boolean`	(optional) Set this option to `true` to make calls return immediately, without waiting for comparison results. You'll have to rely on the build status for the results. Using this option will also allow you to schedule future comparisons on reports that are currently being processed.
`fallbackShas`	`Array<String>`	(optional) Provide a list of shas/report identifiers that the comparison is allowed to fall back to, if the `sha1` param isn't matching any reports. The order of this list matters -- put the most desirable fallback first in the list.

Response

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

Get a comparison status

GET /api/reports/:sha1/compare/:sha2/status

URL params

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.

Body params

project String (optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

json ComparisonStatus An object with the current comparison status

Get report comparison statuses

GET /api/reports/:sha/comparison-statuses

URL params

sha String The id of a report.

Query params

project String (optional) The identifying name of the project the reports belong to. If none is specified, the default project will be assumed.

Response

json Array<ComparisonStatus> A list of comparison statuses for the :sha

Get comparisons

GET /api/comparisons

Query params

`from`	`Date`	(optional) (An ISO 8601 string) Get comparisons created after this timestamp.
`to`	`Date`	(optional) (An ISO 8601 string) Get comparisons created before this timestamp.
`limit`	`Number`	(optional) Default 10. Controls how many items are returned.
`project`	`String`	(optional) The name of the project to return comparisons for. If left out, comparisons for all projects will be returned.

Response

json Array<ComparisonStatus> A list of comparison statuses

Create an orchestration job

POST /api/jobs/:sha1/:sha2/orchestrate

URL params

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.

Body params

`projects`	`Array<String>`	A list of projects (identifying names) that you want to be part of the job.
`link`	`String`	(optional) URL to the source of the orchestration job (e.g. PR URL).
`message`	`String`	(optional) A short string describing the source of the job (e.g. PR title).

Response

json Job An object with details about the job that was created/found.

Create a job

POST /api/jobs/:sha1/:sha2

URL params

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.

Body params

`project`	`String`	(optional) The project (identifying name) which this job is running for. Leave empty to use the default project.
`projects`	`Array<String>`	(optional) Pass an array of project names to create multiple jobs in one go. If orchestration is used, only one job will be created. If multiple jobs are created, the response will change to an array of jobs.
`link`	`String`	(optional) URL to the source of the job (e.g. PR URL).
`message`	`String`	(optional) A short string describing the source of the job (e.g. PR title).

Response

json Job An object with details about the job that was created/found.

Cancel a job

POST /api/jobs/:sha1/:sha2/cancel

URL params

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.

Body params

`project`	`String`	(optional) The project (identifying name) which this job is running for. Leave empty to use the default project.
`status`	`String`	(optional) Either "failure" or "success". This will control what status will be posted to GitHub. The default is "failure".
`link`	`String`	(optional) URL to the source of the report (e.g. PR URL).
`message`	`String`	(optional) A description of why the job was cancelled, e.g. "Cancelled in CI"

Fail a job

POST /api/jobs/:sha1/:sha2/fail

Get jobs

GET /api/jobs

Query params

`from`	`Date`	(optional) (An ISO 8601 string) Get jobs created after this timestamp.
`to`	`Date`	(optional) (An ISO 8601 string) Get jobs created before this timestamp.
`limit`	`Number`	(optional) Default 10. Controls how many items are returned. Max is 100 -- if you specify a larger number you will still get at most 100 back.

Response

json Array<JobDetail> A list of jobs

Get a job

GET /api/jobs/:id

URL params

id Number The ID of the job

Response

json JobDetail Details about the job

Ignore diff

POST /api/ignored-diffs

Body params

`snapshot1Id`	`String`	A snapshot id
`snapshot2Id`	`String`	A snapshot id

Add component subscriptions

POST /api/subscriptions/:component

URL params

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

Body params

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

Remove component subscriptions

DELETE /api/subscriptions/:component

URL params

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

Body params

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

Get snapshotExperimental

GET /api/components/:component/:variant/:target

URL params

`component`	`String`	The name of a component. Should match component names that are in the reports.
`variant`	`String`	The name of the variant. Should match variant names that are in the reports.
`target`	`String`	The target of the snapshot. Should match target names that are in the reports.

Query params

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

Response

json Snapshot An object with details about the snapshot.

Skip

POST /api/skip/:sha

URL params

sha String The sha of the commit to skip.

Body params

`project`	`String`	(optional) The identifying name of the project associated with the call.
`label`	`String`	(optional) An optional message to use with the build status (default is "Skipped")

Clone report

POST /api/reports/:fromSha/clone/:toSha

URL params

`fromSha`	`String`	The id of the report to clone from
`toSha`	`String`	The id of the report to clone to

Body params

`project`	`String`	(optional) The identifying name of the project for which the clone should be created. If none is specified, the default project will be used.
`link`	`String`	(optional) URL to the source of the report (e.g. PR URL). If omitted, the link from the source/from report will be used
`message`	`String`	(optional) A short string describing the source of the report (e.g. PR title). If omitted, the link from the source/from report will be used.

Response

json ReportStatus An object containing a url where the uploaded report can be accessed

Get diff counts

GET /api/diff-counts

Query params

`project`	`String`	(optional) The identifying name of the project to fetch diff counts for. If none is specified, the default project will be used.
`from`	`Date`	(optional) (An ISO 8601 string) Show diff counts after this point in time. Default is 30 days ago.
`to`	`Date`	(An ISO 8601 string) Show diff counts up until this point in time. If you don't pass in this parameter, you'll get diff counts up until the current timestamp.

Response

json Array An ordered list of components and their respective diff counts.

Get current usage

GET /api/billing/current-usage

Response

json Usage Usage information for the current billing cycle

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

`url`	`String`	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.
`variant`	`String`	The name of the variant (e.g. "disabled")
`target`	`String`	The snapshot's target (e.g. "firefox", "iphone 7")
`component`	`String`	The name of the component shown in the screenshot (e.g. "Button")
`height`	`Number`	The pixel height of the screenshot image
`width`	`Number`	The pixel width of the screenshot image
`id`	`String`	A unique identifier for the snapshot

ReportStatus

An object with useful properties for a report.

`url`	`String`	A URL leading to the report page
`completedAt`	`Date`	(An ISO 8601 string) Present if all the partials for a report have been added. Null otherwise. If you're not using partial reports, this value is always present.
`createdAt`	`Date`	(An ISO 8601 string) The timestamp for when the report was initially created.
`snapshotCount`	`Number`	The total number of snapshots included in the report

Comparison

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

`diffs`	`Array<Array<Snapshot>>`	A list of snapshots that are different. Each item in the array is a tuple/array with the before snapshot and the after snapshot.
`added`	`Array<Snapshot>`	Snapshots that have been added
`deleted`	`Array<Snapshot>`	Snapshots that have been removed
`unchanged`	`Array<Snapshot>`	A list of identical snapshots
`summary`	`String`	A summary of the results, with the most important information listed
`equal`	`Boolean`	True if the two reports are identical, false otherwise
`status`	`String`	Either "failure" or "success". If the two reports are equal, or a user has manually accepted the comparison, the value is "success". If the two reports are not equal, or a user has manually rejected the comparison, the value is "failure".
`compareUrl`	`String`	A link to a happo report page
`statusImageUrl`	`String`	A link to an image showing the status for the comparison

ComparisonStatus

An object with information about the status of a comparison.

`sha1`	`String`	The id of the "before" report.
`sha2`	`String`	The id of the "after" report.
`status`	`String`	One of three values: "success" when the comparison is approved, "failure" when the comparison has been rejected or "awaiting review" when the comparison needs a review
`url`	`String`	A URL leading to the comparison page
`createdAt`	`Date`	(An ISO 8601 string) The timestamp for when the comparison was initially created.
`diffs`	`Number`	The number of diffs in this comparison
`unchanged`	`Number`	The number of unchanged snapshots
`added`	`Number`	The number of added snapshots
`deleted`	`Number`	The number of added snapshots
`link`	`String`	A URL leading to the PR/commit that triggered the comparison
`message`	`String`	A description of the PR/commit that triggered the comparison
`project`	`String`	The name of the project that this comparison belongs to

Job

A small object with basic properties for a job.

`url`	`String`	A URL leading to the job page
`id`	`Number`	A unique identifier for the job

Usage

Snapshots usage information

`total`	`Number`	The number of snapshots used in a billing cycle
`quota`	`Number`	The number of snapshots included in the subscription
`start`	`Date`	(An ISO 8601 string) The timestamp when the billing cycle starts
`end`	`Date`	(An ISO 8601 string) The timestamp when the billing cycle ends

JobDetails

An object with useful properties for a job.

`id`	`Number`	A unique identifier for the job
`createdAt`	`Date`	(An ISO 8601 string) The creation timestamp for the job
`finishedAt`	`Date`	(An ISO 8601 string) The timestamp when the job finished
`sha1`	`String`	The ID of the "before" report
`sha2`	`String`	The ID of the "after" report
`description`	`String`	A description of the status that the job has
`status`	`String`	Can be "failure", "success", or "pending"
`link`	`String`	(optional) URL to the source of the job (e.g. PR URL).
`message`	`String`	(optional) A short string describing the source of the job (e.g. PR title).
`url`	`String`	A URL leading to the job page