Trigger notification request to t3extensions.org
(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.