GitLab

(as discussed with Thomas Löffler and Mathias Schreiber on Slack)

Real-time Notification of Extension Updates

Feature Overview

This new feature triggers an HTTPS request to a specific API endpoint at t3extensions.org, whenever a new extension version gets uploaded or a new extension published at the TER.

Benefits

Currently, t3extensions.org features a Slash command for typo3.slack.com to allow users to retrieve details of an extension (see typical use case below). The underlying NoSQL database gets updated a few times a day only, so the extension details are sometimes outdated.

By implementing the feature described below, we aim for a real-time update of the data, so Slack would always show accurate details of extensions.

Use Case

In any channel (public or private) or direct message communication between users on typo3.slack.com, command /extension <extension_key> returns details about the extension with extension key equals <extension_key>. This has been implemented and is available and actually used already.

For example:

/extension powermail

Details such extension title, key, author, latest version, last update date, description, etc. is posted into the Slack channel, assuming the extension exists.

Requirements

As soon as a new TYPO3 extension version gets uploaded to the TER, a POST request should be triggered to a specific API endpoint. The endpoint URL should be configurable. The payload (data in the body of the request) is a JSON object with the following keys/values.

{
  "token": "<token>",
  "source": "extensions.typo3.org",
  "data": {
    "extension_key": "<extension_key>",
    "version": "<version>",
    "integer_version": "<integer_version>",
    "state": "<state>",
    "title": "<title>",
    "description": "<description>",
    "author_name": "<author_name>",
    "last_updated": "<timestamp>"
  }
}

Key:	Description:	Example:	Notes:
token	Access token	AEEK4K2a8OgSRcXz	(1)
source	Source identifier	extensions.typo3.org	(2)
data	JSON object, see below
data → extension_key	Extension key	powermail
data → version	Extension version (format: X.Y.Z)	1.2.3
data → integer_version	Extension integer version	1002003
data → state	Extension state (arbitrary text)	beta
data → title	Extension title (arbitrary text)	Powermail
data → description	Extension description (arbitrary text)	Lorem ipsum...
data → author_name	Extension author (arbitrary text)	Brad Pitt
data → last_updated	UNIX timestamp of last update in UTC	1514524068

Notes

(1) The access token should be configurable. The token must be classified as sensitive information and is therefore not included in this publicly accessible feature request. Please contact me on Slack: https://typo3.slack.com/messages/D1KECK1EF

(2) The source identifies, which service or server initiates the request. Useful for debugging purposes at t3extensions.org. In case the TER runs in a distributed server setup, the host name can be used as the source. Otherwise, extensions.typo3.org could be a good value.

API Endpoint URLs

Method: Update Extension

A POST request to https://slack.t3extensions.org/v1/UpdateExtension updates the details of a specific extension. This request requires a valid token and further data (see details above) as the payload.

The API method automatically detects, if the details of an existing extension need to be updated or if the request is for a new extension (first version of an extension). The <extension_key> is used as the identifier.

Method: Show Test Table

The UpdateExtension API method uses a test database table during development. To retrieve the data of this test table, a GET request to https://slack.t3extensions.org/v1/ShowTestTable can be executed.

API Tests

Update Extension Details on Command Line

# DATA='{"token": "secret-token", "source": "testing", "data": {"extension_key": "myextension", "version": "1.2.3", "integer_version": "1002003", "state": "alpha", "title": "My Test Extension", "description": "This is just a test entry for t3extensions.org", "author_name": "Johnny Depp", "last_updated": "1512270379"}}'
# curl -s -X POST --data "${DATA}" -H "Content-Type: application/json" https://slack.t3extensions.org/v1/UpdateExtension

Retrieve Data from Test Table on Command Line

# curl -s https://slack.t3extensions.org/v1/ShowTestTable

The content of the test table can also be access in a standard browser of course: https://slack.t3extensions.org/v1/ShowTestTable

Error Handling

If the data update fails, the API method returns a JSON object with an error description. For example:

{
  "result": "failed",
  "request_id": "4083432a-ec5c-11e7-bed9-f33584834239",
  "response": [
    {
      "message": "Security token mismatch",
      "code": 102
    }
  ]
}

Restrictions

The code at t3extensions.org uses a cloud-based, serverless microservice at Amazon Web Services. In order to control resources and costs, the number of read/write operations to the NoSQL database and the CPU and memory consumption of the API methods are limited intentionally. Too many requests within a certain time frame may result in an error message.

Version 1 of API method UpdateExtension currently supports one update request only. As a logical consequence, each extension update requires a notification request to the API method. The update of multiple extensions in one request is not supported at this point in time.