Public API

The API is RESTful and is hosted on https://yellowlab.tools/api. You can call it from any language able to send an HTTP request, or from a browser (CORS allowed).

Launch a run

POST https://yellowlab.tools/api/runs

The parameters are sent in the body as JSON. For this, your need to:

• add this header Content-Type: application/json
• send the parameters in the body in JSON. Please check you are sending valid JSON, otherwise you will receive a SyntaxError message.

Body parameters in POST request example:

{
  "url": "http://www.google.com",
  "waitForResponse": true
}

Parameters

url [String]

The URL of the page you want to test (mandatory). If no protocol is specified, http:// will automatically be added.

device [String]

Use "phone" or "tablet" to simulate a mobile device (by user-agent and viewport size). Default is "desktop".

screenshot [Boolean]

If true, takes a screenshot of the loaded webpage. Default is false.
The screenshot is a small, low-quality JPG thumbnail as it is optimized for minimal disk space. If you need a high quality screenshot, consider using the command-line or the NodeJS module.
The JSON result will contain an additional screenshotUrl property. This url can also be guessed from the runId: https://yellowlab.tools/api/results/<runId>/screenshot.jpg.

waitForResponse [Boolean]

This API request can work in two modes. With waitForResponse set to false (default), the request will respond instantly with a runId. You will then be able to request the run's status (position in queue) and poll it until the run is complete. See Check the status of a run. With waitForResponse set to true (deprecated, as the connection can sometimes hang up unexpectedly), it will wait until the run is finished, then send a 302 redirect to the result route for the run. See Retrieve the result. You might need to configure your HTTP request manager to follow redirects.

partialResult [String]

When waitForResponse is true, the default behavior is to redirect you to the full result JSON, which is heavy. If you only need a part of it, you can use this option to indicate which part of the response you need.

• generalScores redirects the query to /api/results/<runId>/generalScores
• rules redirects the query to /api/results/<runId>/rules
• javascriptExecutionTree redirects the query to /api/results/<runId>/javascriptExecutionTree
• phantomas redirects the query to /api/results/<runId>/toolsResults/phantomas

proxy [String]

Uses the defined HTTP proxy to access the website. Syntax is host:port.

cookie [String]

Adds a cookie for a domain. Multiple cookies can be set, using a pipe separator. Example: "bar1=foo1;domain=.domain1.com|bar2=foo2;domain=www.domain2.com".

Basic HTTP authentication

Use authUser and authPass to send the authentication username and password. If your authentication is not basic (form based), you might be able to copy the session cookie from your browser, paste it in the cookie parameter and launch a run before your cookie expires.

blockDomain [String]

Disallow requests to given domain(s), aka blacklist. Comma separated.

allowDomain [String]

Allow requests to given domain(s), aka whitelist. Comma separated.

noExternals [Boolean]

Block requests to all 3rd party domains.

Check the status of a run

When launching a run with waitForResponse set to false, the API immediatly responds a simple JSON similar to {"runId": "abc123"}.
The run is pushed in a waiting queue which launches one run at a time.

You can then ask the status of the run with this request:

GET https://yellowlab.tools/api/runs/<runId>

Response:

{
  "runId": "abc123",
  "params": { "url": "http://www.google.com" },
  "status": {
    "statusCode": "awaiting",
    "position": 2
  }
}

statusCode can have these values:

• awaiting: waiting behind some other runs. The position attribute is only available when statusCode is awaiting. A position of 2 in this example means you are waiting behind the current run and another one.
• running: processing...
• complete: the run is done, you can now retrieve the results.
• failed: an error occurred. An error attribute containing a message is given.

Retrieve the result

One the run is complete, you can get the result with this request:

GET https://yellowlab.tools/api/results/<runId>

If the run is not yet complete or if the run failed, the API will respond with a 404 Not found error. Otherwise, you receive the full JSON.
See the JSON output format here.

Exclude some parts of the result

You can exclude some fields (for a smaller response) by adding an exclude param to the query string (comma-separated).

GET https://yellowlab.tools/api/results/<runId>?exclude=<fieldName1>,<fieldName2>

Retrieve a part of the result only

If you don't need the entire JSON, you can specify which part of the response you want, by telling which part you need at the end of the url.

GET https://yellowlab.tools/api/results/<runId>/generalScores
=> Returns the calculated general score and all the category scores

GET https://yellowlab.tools/api/results/<runId>/rules
=> Returns the scores for each YLT rule and offenders

GET https://yellowlab.tools/api/results/<runId>/javascriptExecutionTree
=> Returns the JavaScript profiling informations

GET https://yellowlab.tools/api/results/<runId>/phantomas
=> Returns the raw JSON result from Phantomas

Retrieve the screenshot

If the run was launched with the screenshot option, the image will be available at this URL:

GET https://yellowlab.tools/api/results/<runId>/screenshot.jpg

Anti flood

To avoid abuse and keep the service free for everyone, the API will block your IP address in case of overuse. Please don't launch more than 25 runs per 24h and more than 200 tests per month. If you have a good reason, please email me so I can give you an api-key. Otherwise, please create and host your private instance.