A New Lighthouse REST API to Automate Testing for a New Day in SEO

As Google continues steps towards a new search algorithm change focused on page experience (rollout starting in June), Foo has released version 2 of its REST API to provide more tools for automated Lighthouse testing. Foo can be used to establish a historical record of Lighthouse audits to analyze website performance, SEO, accessibility and best practice. In a dashboard you can manage pages to run Lighthouse audits against manually and automatically. Now you can do all this programmatically via our REST API!

Version 1 of our API provided a single endpoint to enqueue Lighthouse audits, but version 2 provides much more. Additionally, we released a Node.js API client and a documentation website.

This post will provide a demo of each new endpoint. For a deeper dive of endpoints, authentication, responses, etc - check out our new documentation website linked below.

Managing Pages

On Foo you can manage pages from a dashboard. Lighthouse audits run on these pages a certain number of times each day based on your account type. You can also trigger audits on any page manually via the UI.

Pages on Foo's dashboard

You can now create, edit and delete pages from the new REST API.

Listing Pages

In this example we get a list of pages we created on Foo. We limit our result count to 5.

curl -X GET "https://www.foo.software/api/v2/pages?limit=5" \
  -H "authorization: abc123"

The response would look something like this.

{
  "data": [
    {
      "url": "https://www.foo.software/lighthouse",
      "createdAt": "2020-09-06T17:50:00.127Z",
      "device": "mobile",
      "name": "Lighthouse Page",
      "id": "5f55214823d9f90038cb2d7b"
    },
    {
      "name": "Web Vitals Page",
      "device": "mobile",
      "id": "5f55201023d9f90038cb2d74",
      "createdAt": "2020-09-06T17:44:48.862Z",
      "url": "https://www.foo.software/web-vitals/"
    }
  ]
}

Creating a Page

curl -X POST "https://www.foo.software/api/v2/pages" \
  -H "authorization: abc123" \
  -H "content-type: application/json" \
  -d "{ \"url\": \"https://www.foo.software\", \"name\": \"Foo home page\" }"

The above would yield a response like the below.

{
  "data": {
    "url": "https://www.foo.software",
    "createdAt": "2020-09-06T17:50:00.127Z",
    "device": "mobile",
    "name": "Foo home page",
    "id": "5f55214823d9f90038cb2d7b"
  }
}

Updating a Page

curl -X PUT "https://www.foo.software/api/v2/pages/123" \
  -H "authorization: abc123" \
  -H "content-type: application/json" \
  -d "{ \"name\": \"Foo home page (updated name)\" }"

Removing a Page

curl -X DELETE "https://www.foo.software/api/v2/pages/123" \
  -H "authorization: abc123" \
  -H "content-type: application/json"

Managing the Queue

Foo builds a queue of Lighthouse audits to run on a "First In First Out" basis. In the page detail screen of Foo's dashboard you can see the queue at work especially if you've manually triggered a couple audits in a row.

Queued Lighthouse audits on Foo's dashboard

Listing Queue Items

In this example we get a list of pages in the queue to be audited by Lighthouse. Note we get this list by page ID.

curl -X GET "https://www.foo.software/api/v2/pages/12345/queueItems" \
  -H "authorization: abc123"

The response would look something like this.

{
  "data": [
    {
      "createdAt": "2021-05-04T21:15:10.499Z",
      "id": "1620162910499-5aad2db2-1ad3-4556-b043-987e6fccf423",
      "index": 0,
      "pageId": "608ef83194f4a905853256f3",
      "tag": "PR #1",
      "type": "lighthouseAudit",
      "waitSeconds": 30
    },
    {
      "createdAt": "2021-05-04T21:15:10.499Z",
      "id": "1620162936866-8cec2bd7-5d69-40c8-a0b8-a5cc33ba16a3",
      "index": 1,
      "pageId": "608ef83194f4a905853256f3",
      "tag": "PR #2",
      "type": "lighthouseAudit",
      "waitSeconds": 40
    }
  ]
}

What all these fields mean exactly may not be obvious. This is one reason why we now have a documentation website. For full details about fields and this data in general, your best bet is reading through the "Resources" section of our API documentation.

Adding a Page to the Queue

curl -X POST "https://www.foo.software/api/v2/pages" \
  -H "authorization: abc123" \
  -H "content-type: application/json" \
  -d "{ \"tag\": \"PR #2\" }"

The above would yield a response like the below.

{
  "data": {
    "createdAt": "2021-05-04T21:15:10.499Z",
    "id": "1620162936866-8cec2bd7-5d69-40c8-a0b8-a5cc33ba16a3",
    "index": 1,
    "pageId": "608ef83194f4a905853256f3",
    "tag": "PR #2",
    "type": "lighthouseAudit"
  }
}

Managing Lighthouse Audits

Queue items are created with an association to pages and eventually, a queue item triggers a Lighthouse audit. Upon audit completion, a representation of the Lighthouse audit is saved to our database, and the corresponding queue item is deleted. In this way, you can think of queue items as ephemeral. Records of Lighthouse audits are stored in our database and can also be managed in the UI and now via REST API.

A record of a Lighthouse audit on Foo's dashboard

Listing Lighthouse Audits

In this example we get a list of completed Lighthouse audits stored on Foo. Note we get this list by page ID.

curl -X GET "https://www.foo.software/api/v2/pages/12345/lighthouseAudits" \
  -H "authorization: abc123"

The response would look something like this.

{
  "data": [
    {
      "createdAt": "2021-05-04T20:38:14.216Z",
      "finalScreenshot": "https://foo-software-lighthouse-reports-dev.s3.amazonaws.com/final-screenshot-1620160694001.jpg",
      "id": "6091b0b6fe6f77002f230306",
      "lighthouseVersion": "7.3.0",
      "opportunities": [
        {
          "id": "uses-webp-images",
          "numericUnit": "millisecond",
          "numericValue": 9230,
          "rating": "fail"
        },
        {
          "id": "uses-responsive-images",
          "numericUnit": "millisecond",
          "numericValue": 4000,
          "rating": "fail"
        },
        {
          "id": "unused-javascript",
          "numericUnit": "millisecond",
          "numericValue": 160,
          "rating": "average"
        }
      ],
      "pageId": "608ef83194f4a905853256f3",
      "queueId": "1620160629054-2ff90d34-179c-458e-90c0-68ebde9499e7",
      "report": "https://foo-software-lighthouse-reports-dev.s3.amazonaws.com/report-1620160693103.html",
      "scoreAccessibility": 95,
      "scoreBestPractices": 87,
      "scorePerformance": 99,
      "scoreProgressiveWebApp": 42,
      "scoreSeo": 98,
      "tag": "PR #2",
      "url": "https://www.foo.software"
    },
    {
      "createdAt": "2021-05-03T18:51:13.515Z",
      "finalScreenshot": "https://foo-software-lighthouse-reports-dev.s3.amazonaws.com/final-screenshot-1620067873314.jpg",
      "id": "60904621a87f70002fea1903",
      "lighthouseVersion": "7.3.0",
      "opportunities": [
        {
          "id": "uses-webp-images",
          "numericUnit": "millisecond",
          "numericValue": 9030,
          "rating": "fail"
        },
        {
          "id": "uses-responsive-images",
          "numericUnit": "millisecond",
          "numericValue": 4050,
          "rating": "fail"
        },
        {
          "id": "unused-javascript",
          "numericUnit": "millisecond",
          "numericValue": 160,
          "rating": "average"
        }
      ],
      "pageId": "608ef83194f4a905853256f3",
      "queueId": "1620067670955-2dd2e480-ceab-4b2b-b7b1-793b0bd8f6a0",
      "report": "https://foo-software-lighthouse-reports-dev.s3.amazonaws.com/report-1620067872741.html",
      "scoreAccessibility": 95,
      "scoreBestPractices": 87,
      "scorePerformance": 99,
      "scoreProgressiveWebApp": 42,
      "scoreSeo": 98,
      "tag": "PR #1",
      "url": "https://www.foo.software"
    }
  ]
}

Refer to the "Resources" section of our documentation for details about what all these fields mean.

Updating a Lighthouse Audit

curl -X PUT "https://www.foo.software/api/v2/lighthouseAudits/12345" \
  -H "authorization: abc123" \
  -H "content-type: application/json" \
  -d "{ \"tag\": \"Starting with this audit things went downhill\" }"

Removing a Lighthouse Audit

curl -X DELETE "https://www.foo.software/api/v2/lighthouseAudits/12345" \
  -H "authorization: abc123" \
  -H "content-type: application/json"

Conclusion

I hope this post provides a good overview of what is possible with our new REST API. We plan to extend this API as we grow the functionalities of our services and eventually expose a GraphQL API.