REST • 5 min read

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

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.

Next.js, GraphQL, Recoil, MUI and More: A New Web Stack Reviewed
Next.js

Next.js, GraphQL, Recoil, MUI and More: A New Web Stack Reviewed

With our website redesign we revamped our technology stack. This post reviews choices including Next.js, GraphQL, MUI (Material UI), and TypeScript.

Read more

A New Day in SEO and a New Foo - Lighthouse, Web Vitals and Page Experience
foo

A New Day in SEO and a New Foo - Lighthouse, Web Vitals and Page Experience

An overview of the newly released version of www.foo.software, a website leveraging Lighthouse, Web Vitals and Binoculars tools to provide page experience testing services.

Read more

How to Collect and Analyze Web Vitals from Next.js for Page Experience
Web Vitals

How to Collect and Analyze Web Vitals from Next.js for Page Experience

Google's Web Vitals is becoming the standard for measuring page experience. As of version 9.4 of Next.js, it provides a built-in method for capturing and reporting Core Web Vitals. This post illustrates how to collect Web Vitals metrics from a Next.js app and send them to a service for storage.

Read more