API

The Tide API is a Docker implementation of MySQL, PHP-FPM, and Nginx. The web server has WordPress installed with this documentation theme and a REST API for storing theme and plugin audits. If you plan on deploying to the cloud you should read the entire Google Cloud Platform section.

The API Docker containers must be up and running before you start any of the other services.

Environment Variables

Commands

Endpoints

The Tide API has several endpoints. I’ll try and cover them in as much detail as possible. One important workflow to note when working with the API is that you must authenticate with the API and generate a token that you then use to make authenticated requests.

/api/tide/v1/auth

Generates a user specific JSON Web Token (JWT) by making a basic authentication POST request with an API key and secret — which can be found on your user profile page.

POST

Usage

Request a JWT with your API key and secret:

curl -X POST \
    http://tide.local/api/tide/v1/auth \
    -F 'api_key=<api_key>' \
    -F 'api_secret=<api_secret>'

/api/tide/v1/audit

This endpoint is used to get audit results and generate audits. There are several ways to generate an audit and reports. One of them is to make a POST request to the audit endpoint in the Tide API. An unauthenticated GET request option is describe lower on this page and is specifically for the wporg user. Another possibility would be to create a message in the queue, but that requires more access than a simple Bearer token.

GET

Request a collection of audits.

POST

Create an audit that generates various report standards for WordPress themes and plugins.

Usage

Create an audit by making a POST request:

curl -X POST \
    http://tide.local/api/tide/v1/audit \
    -H 'Authorization: Bearer <token>' \
    -F 'title=Twenty Seventeen' \
    -F 'content=Twenty Seventeen brings your site to life with header video and immersive featured images.' \
    -F 'slug=twentyseventeen' \
    -F 'project_type=theme' \
    -F 'source_url=https://downloads.wordpress.org/theme/twentyseventeen.2.1.zip' \
    -F 'source_type=zip' \
    -F 'request_client=wporg' \
    -F 'force=false' \
    -F 'visibility=public' \
    -F 'standards[]=phpcs_wordpress' \
    -F 'standards[]=phpcs_phpcompatibility'

/api/tide/v1/audit/{id}

Similar to the previous endpoint but strictly used to make requests to existing audits.

GET

Get an audit by id.

POST

Update an audit by id.

DELETE

Delete an audit by id.

Usage

Retrieve the audit with a GET request:

curl -X GET http://tide.local/api/tide/v1/audit/<id>

Update the title by making a POST request:

curl -X POST \
    http://tide.local/api/tide/v1/audit/<id> \
    -H 'Authorization: Bearer <token>' \
    -F 'title=Something New!'

Force all the report standards to be re-audited by making a POST request:

curl -X POST \
    http://tide.local/api/tide/v1/audit/<id> \
    -H 'Authorization: Bearer <token>' \
    -F 'force=true' \
    -F 'standards[]=phpcs_wordpress' \
    -F 'standards[]=phpcs_phpcompatibility' \
    -F 'standards[]=lighthouse'

And adds the Lighthouse report that was missing in the /api/tide/v1/audit example above.

Remove the audit with a DELETE request and bypass the trash:

curl -X DELETE \
    http://tide.local/api/tide/v1/audit/<id> \
    -H 'Authorization: Bearer <token>' \
    -F 'force=true'

/api/tide/v1/audit/{altid}

This endpoint is nearly identical to the previous one, except you are using the audit’s altid (e.g. checksum) to make your requests. A checksum is an MD5 hash string from the contents of a directory.

GET

Get an audit by altid.

POST

Update an audit by altid.

DELETE

Delete an audit by altid.

/api/tide/v1/audit/{project_client}

GET

Get an audit collection for a project client.

/api/tide/v1/audit/{project_client}/{project_type}

GET

Get a theme or plugin audit collection for a project client.

/api/tide/v1/audit/{project_client}/{project_type}/{project_slug}

GET

Get a theme or plugin audit collection for a project client and slug.

/api/tide/v1/audit/{project_client}/{project_type}/{project_slug}/{version}

This endpoint can be used to make unauthenticated audit requests on behalf of the wporg user if the audit doesn’t already exist. With the wporg user token I could also send an authenticated request to this endpoint and force a re-audit if the audit does exist.

GET

Get a theme or plugin audit for a project client, slug and version.

/api/tide/v1/report/{id}/{type}/{standard}

This endpoint is authenticated and requires a Bearer token. As well, you can only view reports associated with your account. The response is a temporary download link for the report — keeping sensitive data safe and secure is important to us.

GET

Get a specific type of report by id and standard.

/api/tide/v1/report/{altid}/{type}/{standard}

This endpoint has the same restrictions as above.

GET

Get a specific type of report by altid and standard.