diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c717c3c..af90680 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -54,6 +54,7 @@ jobs: id: version run: node scripts/check-version.mjs src/joomla-ws-api.json CHANGELOG.md "$RUNNER_TEMP/base.json" + # Also generates the PhpStorm collection - name: Build run: npm run build diff --git a/.github/workflows/phpstorm.yml b/.github/workflows/phpstorm.yml new file mode 100644 index 0000000..4ef74a0 --- /dev/null +++ b/.github/workflows/phpstorm.yml @@ -0,0 +1,62 @@ +name: PhpStorm branch + +# On every push to main, the PhpStorm HTTP Client collection is generated from the spec and committed to the +# phpstorm branch, when it changed. The commit message names the spec version and the main commit, for instance +# "Generated from 6.2.0 (main 9bd9ea4)". The first run creates the branch. +# The fixed collection of each release is the release file joomla-ws-api--phpstorm.zip. + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: phpstorm-branch + cancel-in-progress: false + +jobs: + phpstorm: + name: Update the phpstorm branch + # Not in forks: there the phpstorm branch can be the head of a pull request. + # Only from main: a manual run from another branch must not push to phpstorm. + if: github.repository == 'joomla-projects/API-Endpoints' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-node@v7 + with: + node-version: 22 + + # The generator only uses Node.js itself: no npm ci needed + - name: Generate the collection + run: node scripts/generate-phpstorm.mjs + + - name: Commit to the phpstorm branch + run: | + version=$(node -p "require('./src/joomla-ws-api.json').info.version") + branch="$RUNNER_TEMP/phpstorm" + if git ls-remote --exit-code --heads origin phpstorm > /dev/null; then + git fetch --quiet --depth 1 origin phpstorm + git worktree add --quiet --detach "$branch" FETCH_HEAD + else + echo "::notice::The phpstorm branch does not exist yet: creating it" + git worktree add --quiet --orphan -b phpstorm-generated "$branch" + fi + cd "$branch" + git rm -r --quiet --ignore-unmatch . + cp -a "$GITHUB_WORKSPACE/dist/phpstorm/." . + git add -A + if git diff --cached --quiet; then + echo "The collection did not change." + exit 0 + fi + git -c user.name="github-actions[bot]" -c user.email="41898233+github-actions[bot]@users.noreply.github.com" \ + commit --quiet -m "Generated from $version (main ${GITHUB_SHA::7})" + git push --quiet origin HEAD:refs/heads/phpstorm + git log -1 --stat --format='%s' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9b65470..c785dc2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,7 @@ name: Release # Push a tag that equals info.version of src/joomla-ws-api.json, for instance 6.2.1: # git tag -a 6.2.1 -m "Joomla Web Services API 6.2.1" && git push origin 6.2.1 -# The release gets the files joomla-ws-api-.json, .yaml, .html and .sha256. +# The release gets the files joomla-ws-api-.json, .yaml, .html, -phpstorm.zip and .sha256. # The highest version becomes the "latest" release: # https://api.github.com/repos/joomla-projects/API-Endpoints/releases/latest @@ -57,7 +57,7 @@ jobs: | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1) latest=false [ "$highest" = "$GITHUB_REF_NAME" ] && latest=true - gh release create "$GITHUB_REF_NAME" dist/* \ + gh release create "$GITHUB_REF_NAME" dist/joomla-ws-api-* \ --verify-tag \ --title "Joomla Web Services API $GITHUB_REF_NAME" \ --notes-file notes.md \ diff --git a/README.md b/README.md index c990d75..51b2c78 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ The specification is one file: [`src/joomla-ws-api.json`](src/joomla-ws-api.json | Not yet released (`main`) | https://raw.githubusercontent.com/joomla-projects/API-Endpoints/main/src/joomla-ws-api.json | Each release has these files, with its version in the name: `joomla-ws-api-.json`, the same spec in -YAML (`.yaml`), readable documentation (`.html`, Redoc) and checksums (`.sha256`). +YAML (`.yaml`), readable documentation (`.html`, Redoc), the [PhpStorm collection](#phpstorm-collection) +(`-phpstorm.zip`, since 6.2.1) and checksums (`.sha256`). For AI agents and other tools: the JSON of the latest release has the version in `tag_name`, and the download URL of each file in `assets[].browser_download_url`. For instance: @@ -51,6 +52,22 @@ The [`bruno`](https://github.com/joomla-projects/API-Endpoints/tree/bruno) branc [Bruno](https://www.usebruno.com) collection of the Joomla 6 API endpoints, made by René Kreijveld ([@renekreijveld](https://github.com/renekreijveld)). It is not yet up to date with this specification. +## PhpStorm collection + +A collection for the HTTP Client of PhpStorm and other JetBrains IDEs: a request for every operation of the +specification, with its example request body. It is generated from the specification, so it is always up to date +with it. + +- **A release**: each release since 6.2.1 has the collection of that version in + `joomla-ws-api--phpstorm.zip`. +- **The [`phpstorm`](https://github.com/joomla-projects/API-Endpoints/tree/phpstorm) branch**: the collection of the + newest specification in `main`, also with improvements that are not released yet. It is updated automatically on + every change of `main`. + +Its [README](scripts/phpstorm/README.md) explains how to set it up. To generate the collection yourself, run +`npm run phpstorm`: it writes the collection in `dist/phpstorm/`, from +[`scripts/generate-phpstorm.mjs`](scripts/generate-phpstorm.mjs) and the files in [`scripts/phpstorm`](scripts/phpstorm). + ## Credits The specification was made by Sergey Tolkachyov ([@sergeytolkachyov](https://github.com/sergeytolkachyov)) for the Joomla Manual diff --git a/package.json b/package.json index 5176e92..80f8e26 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,7 @@ "lint": "redocly lint src/joomla-ws-api.json --format=stylish", "quality": "node scripts/check-quality.mjs src/joomla-ws-api.json", "routes": "node scripts/check-routes.mjs src/joomla-ws-api.json", + "phpstorm": "node scripts/generate-phpstorm.mjs", "check": "npm run format:check && npm run validate:schema && npm run lint && npm run quality", "build": "node scripts/build.mjs" }, diff --git a/scripts/build.mjs b/scripts/build.mjs index b8241c3..b8abd66 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -3,7 +3,9 @@ // joomla-ws-api-.json the spec, unchanged // joomla-ws-api-.yaml the same spec in YAML // joomla-ws-api-.html readable documentation (Redoc) +// joomla-ws-api--phpstorm.zip the PhpStorm HTTP Client collection (scripts/generate-phpstorm.mjs) // joomla-ws-api-.sha256 checksums of the files above +// The collection is also left unzipped in dist/phpstorm/. // // Usage: node scripts/build.mjs [--tag ] // --tag: fail unless the tag equals info.version of the spec (used by the release workflow). @@ -12,6 +14,7 @@ import { execFileSync } from 'node:child_process'; import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; +import zlib from 'node:zlib'; import { loadSpec } from './lib.mjs'; const SRC = 'src/joomla-ws-api.json'; @@ -34,13 +37,66 @@ const redocly = (...a) => { execFileSync(process.execPath, [path.join('node_modules', '@redocly', 'cli', 'bin', 'cli.js'), ...a], { stdio: 'inherit' }); }; +/** + * Writes a zip file of the files in dir, in the folder root of the zip. Fixed dates, so a build is reproducible. + * Only a flat folder: a subfolder is an error. + */ +function zip(dir, root, target) { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const other = entries.filter((e) => !e.isFile()).map((e) => e.name); + if (other.length) throw new Error(`zip: ${dir} may only contain files, not: ${other.join(', ')}`); + const names = entries.map((e) => e.name).sort(); + const local = []; + const central = []; + let offset = 0; + for (const name of names) { + const data = fs.readFileSync(path.join(dir, name)); + const deflated = zlib.deflateRawSync(data, { level: 9 }); + const fileName = Buffer.from(`${root}/${name}`); + const crc = zlib.crc32(data); + // version 2.0, flags (UTF-8 names), deflate, time 00:00, date 1980-01-01, crc, sizes, name length, extra length + const fields = (b, at) => { + b.writeUInt16LE(20, at); + b.writeUInt16LE(0x0800, at + 2); + b.writeUInt16LE(8, at + 4); + b.writeUInt16LE(0, at + 6); + b.writeUInt16LE(0x21, at + 8); + b.writeUInt32LE(crc, at + 10); + b.writeUInt32LE(deflated.length, at + 14); + b.writeUInt32LE(data.length, at + 18); + b.writeUInt16LE(fileName.length, at + 22); + }; + const header = Buffer.alloc(30); + header.writeUInt32LE(0x04034b50, 0); + fields(header, 4); + const entry = Buffer.alloc(46); + entry.writeUInt32LE(0x02014b50, 0); + entry.writeUInt16LE(20, 4); + fields(entry, 6); + entry.writeUInt32LE(offset, 42); + local.push(header, fileName, deflated); + central.push(entry, fileName); + offset += header.length + fileName.length + deflated.length; + } + const directory = Buffer.concat(central); + const end = Buffer.alloc(22); + end.writeUInt32LE(0x06054b50, 0); + end.writeUInt16LE(names.length, 8); + end.writeUInt16LE(names.length, 10); + end.writeUInt32LE(directory.length, 12); + end.writeUInt32LE(offset, 16); + fs.writeFileSync(target, Buffer.concat([...local, directory, end])); +} + const base = `joomla-ws-api-${version}`; -const files = [`${base}.json`, `${base}.yaml`, `${base}.html`]; +const files = [`${base}.json`, `${base}.yaml`, `${base}.html`, `${base}-phpstorm.zip`]; // The spec is one self-contained file: the release JSON is the source file as it is. fs.copyFileSync(SRC, `${DIST}/${base}.json`); redocly('bundle', SRC, '--output', `${DIST}/${base}.yaml`); redocly('build-docs', SRC, '--output', `${DIST}/${base}.html`, '--title', `Joomla ${version} Web Services API`); +execFileSync(process.execPath, ['scripts/generate-phpstorm.mjs', SRC], { stdio: 'inherit' }); +zip(`${DIST}/phpstorm`, `${base}-phpstorm`, `${DIST}/${base}-phpstorm.zip`); const sums = files.map((f) => `${crypto.createHash('sha256').update(fs.readFileSync(path.join(DIST, f))).digest('hex')} ${f}`); fs.writeFileSync(`${DIST}/${base}.sha256`, sums.join('\n') + '\n'); diff --git a/scripts/generate-phpstorm.mjs b/scripts/generate-phpstorm.mjs new file mode 100644 index 0000000..7c10f08 --- /dev/null +++ b/scripts/generate-phpstorm.mjs @@ -0,0 +1,137 @@ +#!/usr/bin/env node +// Generates the PhpStorm HTTP Client collection in dist/phpstorm/ from the spec: one .http file per tag, with a +// request for each operation, and the files of scripts/phpstorm/ (README and environment files). The request +// bodies are the examples of the spec. The collection is not committed to main: the release has it as a zip file, +// and the phpstorm branch has the collection of the latest main. +// +// Usage: node scripts/generate-phpstorm.mjs [spec.json] (default: src/joomla-ws-api.json) + +import fs from 'node:fs'; +import path from 'node:path'; +import { deref, loadSpec, METHODS } from './lib.mjs'; + +const OUT = 'dist/phpstorm'; +const STATIC = 'scripts/phpstorm'; +const specFile = process.argv[2] ?? 'src/joomla-ws-api.json'; + +// Name of the {id} variable, by the last word of the tag +const ID_NAMES = { + Categories: 'category_id', + Clients: 'client_id', + Form: 'contact_id', + Fields: 'field_id', + Groups: 'group_id', + Levels: 'level_id', + Items: 'menu_item_id', + Styles: 'template_style_id', + Content: 'language_id', + Overrides: 'override_key', + Requests: 'request_id', + Consents: 'consent_id', + Adapters: 'adapter_id', + Newsfeeds: 'feed_id', + Articles: 'article_id', +}; + +// Default values of the path variables +const DEFAULTS = { + adapter_id: 'local-images', + override_key: 'COM_EXAMPLE_KEY', + lang_code: 'en-GB', + component_name: 'com_content', + path: 'local-images:/joomla_black.png', +}; + +/** "Banners Categories" -> "category_id". Content history uses the ID of the item it belongs to. */ +function idName(tag) { + const words = tag.split(' '); + const last = words.at(-1); + if (last === 'History') return words.at(-3).replace(/s$/, '').toLowerCase() + '_id'; + return ID_NAMES[last] ?? last.replace(/s$/, '').toLowerCase() + '_id'; +} + +const firstSentence = (text) => text.trim().split(/(?<=\.)\s/)[0]; + +function bodyExample(content) { + const media = content['application/json'] ?? Object.values(content)[0]; + if ('example' in media) return media.example; + if (media.examples) return deref(spec, Object.values(media.examples)[0]).value; + return {}; +} + +const spec = loadSpec(specFile); +const files = new Map(); + +// The operations in the order of the spec (operations() of lib.mjs sorts the methods) +const ordered = Object.entries(spec.paths).flatMap(([route, pathItem]) => + Object.keys(pathItem) + .filter((method) => METHODS.includes(method)) + .map((method) => ({ route, method, operation: pathItem[method], pathItem })), +); + +for (const { route, method, operation, pathItem } of ordered) { + const tag = operation.tags[0]; + const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])].map((p) => deref(spec, p)); + const variables = {}; + const notes = []; + let url = route; + for (const p of parameters.filter((p) => p.in === 'path')) { + let name = p.name; + if (name === 'id') name = (p.description ?? '').includes('ID of the version') ? 'version_id' : idName(tag); + url = url.replace(`{${p.name}}`, `{{${name}}}`); + variables[name] = p.example ?? DEFAULTS[name] ?? 1; + if (p.description) notes.push(`{{${name}}}: ${firstSentence(p.description)}`); + } + const security = operation.security ?? spec.security ?? []; + const requestBody = deref(spec, operation.requestBody); + if (!files.has(tag)) files.set(tag, []); + files.get(tag).push({ + summary: operation.summary, + method: method.toUpperCase(), + url: `{{base_url}}${url}`, + variables, + notes: [...new Set(notes)], + query: parameters.filter((p) => p.in === 'query').map((p) => p.name), + updateToken: security.some((s) => 'JUpdateToken' in s), + body: requestBody ? bodyExample(requestBody.content) : null, + }); +} + +/** The contents of the .http file of one tag. */ +function render(tag, requests) { + const lines = [ + `# ${tag}`, + '#', + `# Generated from the OpenAPI spec of the Joomla Web Services API ${spec.info.version}.`, + '# Set base_url and api_key in http-client.env.json and http-client.private.env.json.', + '', + ]; + const variables = {}; + for (const r of requests) { + for (const [name, value] of Object.entries(r.variables)) variables[name] ??= value; + } + for (const [name, value] of Object.entries(variables)) lines.push(`@${name} = ${value}`); + if (Object.keys(variables).length) lines.push(''); + + for (const r of requests) { + lines.push(`### ${r.summary}`, `# @name ${r.summary}`); + for (const note of r.notes) lines.push(`# ${note}`); + if (r.query.length) lines.push(`# Optional query parameters: ${r.query.join(', ')}`); + lines.push(`${r.method} ${r.url}`); + lines.push(r.updateToken ? 'X-JUpdate-Token: {{update_token}}' : 'X-Joomla-Token: {{api_key}}'); + lines.push('Accept: application/vnd.api+json'); + if (r.body !== null) lines.push('Content-Type: application/json', '', JSON.stringify(r.body, null, 2)); + lines.push(''); + } + return lines.join('\n').trimEnd() + '\n'; +} + +/** "Banners Categories" -> "banners-categories.http" */ +const fileName = (tag) => `${tag.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.http`; + +const requests = [...files.values()].reduce((n, r) => n + r.length, 0); +fs.rmSync(OUT, { recursive: true, force: true }); +fs.mkdirSync(OUT, { recursive: true }); +fs.cpSync(STATIC, OUT, { recursive: true }); +for (const [tag, tagRequests] of files) fs.writeFileSync(path.join(OUT, fileName(tag)), render(tag, tagRequests)); +console.log(`${OUT}: ${files.size} files, ${requests} requests`); diff --git a/scripts/phpstorm/.gitignore b/scripts/phpstorm/.gitignore new file mode 100644 index 0000000..95914b9 --- /dev/null +++ b/scripts/phpstorm/.gitignore @@ -0,0 +1 @@ +http-client.private.env.json diff --git a/scripts/phpstorm/README.md b/scripts/phpstorm/README.md new file mode 100644 index 0000000..cbdf4a8 --- /dev/null +++ b/scripts/phpstorm/README.md @@ -0,0 +1,117 @@ +# PhpStorm HTTP Client collection + +PhpStorm HTTP Client collection for the Joomla 6 Web Services API. + +The collection has a request for every route of the [OpenAPI specification](https://github.com/joomla-projects/API-Endpoints) of the +Joomla Web Services API, with the example request bodies of the specification. It works in PhpStorm and in any other +JetBrains IDE with the built-in [HTTP Client](https://www.jetbrains.com/help/phpstorm/http-client-in-product-code-editor.html). + +## Installation instructions + +### Prepare your Joomla 6 website + +1. Install Joomla 6 on your server or local development environment or use an existing Joomla 6 website. +2. Login into the Joomla 6 administrator panel and go to the Global Configuration. +3. On the **Site** tab make sure that the **Search Engine Friendly URLs** option is enabled. If it isn't, enable it and click the **Save & Close** button at the top. +4. Click on the **User Menu** button at the top right and select **Edit Account**. +5. On the **User Profile** page go to the **Joomla API Token** tab. +6. Check if the token is present, if it isn't, click the **Save** button at the top and the token will be generated. +7. Close the Edit profile page. +8. Go to **System** > **Plugins**. +9. Click on the **Filter Options** button. In the **Select Type** dropdown choose **webservices**. +10. Make sure all Web Services plugins are enabled. If any of them is disabled, enable it and click the **Save & Close** button at the top. + +Your Joomla website is now ready to be used with the webservices API and the PhpStorm collection. + +### Install the collection + +There are two ways to get the collection: + +- **A release**: each [release](https://github.com/joomla-projects/API-Endpoints/releases/latest) since 6.2.1 has the file + `joomla-ws-api--phpstorm.zip`, the collection of that version of the specification. Unzip it. +- **The `phpstorm` branch**: the [`phpstorm`](https://github.com/joomla-projects/API-Endpoints/tree/phpstorm) branch always has the collection + of the newest specification, also with improvements that are not released yet. Clone it, or download it as a zip + file: + ```bash + git clone --branch phpstorm --single-branch https://github.com/joomla-projects/API-Endpoints.git joomla-phpstorm + ``` + +Copy the folder with all its contents into a project you open in PhpStorm, or open the folder itself as a project. + +The folder contains one `.http` file per group of endpoints (a tag in the specification), for example `banners.http` +and `content-articles.http`. + +### Configure the environment + +The requests use two variables: `base_url` and `api_key`. They are set in two environment files in the folder of the +collection. + +1. Open `http-client.env.json` and change the value of `base_url` to the URL of your Joomla website, for example + `https://www.myjoomlawebsite.com/api/index.php`. Keep the `/api/index.php` part at the end of the URL, as that + is the endpoint for Joomla API requests. +2. Copy `http-client.private.env.json.example` to `http-client.private.env.json`. +3. Copy the API token from your Joomla user profile and paste it as the value of `api_key` in + `http-client.private.env.json`. + +The private environment file is listed in `.gitignore`, so your token is not committed by accident. + +The requests in `joomla-update.http` do not use the API token. They use the token of the Joomla Automated Updates +service, which you find in the options of Joomla Update. Set it as the value of `update_token` in +`http-client.private.env.json` if you want to use these requests. + +## Using the collection + +### Running a GET request + +A simple test to see if the API endpoints are working is a `GET` on Config Application. + +1. Open `config-application.http`. +2. In the toolbar at the top of the editor, select the **joomla** environment in the **Run with** dropdown. +3. Click the green run icon in the gutter next to **Get Global Configuration**. The URL for this request is `{{base_url}}/v1/config/application`. +4. If all is working you should see a response with status 200 in the **Services** tool window, with the global + configuration of your Joomla website in JSON format. + +### Using variables in requests + +Requests that work on a single item use a variable in the URL, for example `{{article_id}}`. These variables are +defined at the top of each `.http` file with a default value: + +``` +@article_id = 1 +``` + +First, retrieve a list of articles. + +1. Open `content-articles.http`. +2. Run the request **List Articles**. The URL for this request is `{{base_url}}/v1/content/articles`. +3. If your Joomla website has articles, you should see a response with status 200 and a list of articles in JSON format. + +Retrieve an article with a specific ID. + +1. In the JSON result of the content/articles request, find the ID of an article you want to retrieve. An example ID is shown as `"id": 11`. +2. Change the variable at the top of `content-articles.http` to `@article_id = 11`. +3. Run the request **Get Article**. The URL for this request is `{{base_url}}/v1/content/articles/{{article_id}}`. + +### Query parameters + +List requests support paging, and some also support filters. The available query parameters are listed in a comment +above the request. Add them to the URL, for example: + +``` +# Optional query parameters: page[offset], page[limit], filter[search], filter[state] +GET {{base_url}}/v1/content/articles?filter[search]=joomla&page[limit]=5 +``` + +## Updating the collection + +The `.http` files are generated from the specification by +[`scripts/generate-phpstorm.mjs`](https://github.com/joomla-projects/API-Endpoints/blob/main/scripts/generate-phpstorm.mjs). +Do not change them by hand: to improve a request, change the specification in a pull request to the `main` branch of +[joomla-projects/API-Endpoints](https://github.com/joomla-projects/API-Endpoints). After the merge, the `phpstorm` branch is updated +automatically. + +To generate the collection yourself, from a clone of the `main` branch (Node.js 22 or later): + +```bash +npm run phpstorm # writes the collection in dist/phpstorm/ +``` diff --git a/scripts/phpstorm/http-client.env.json b/scripts/phpstorm/http-client.env.json new file mode 100644 index 0000000..567c079 --- /dev/null +++ b/scripts/phpstorm/http-client.env.json @@ -0,0 +1,5 @@ +{ + "joomla": { + "base_url": "https://yourjoomlasite.com/api/index.php" + } +} diff --git a/scripts/phpstorm/http-client.private.env.json.example b/scripts/phpstorm/http-client.private.env.json.example new file mode 100644 index 0000000..0f6a93b --- /dev/null +++ b/scripts/phpstorm/http-client.private.env.json.example @@ -0,0 +1,6 @@ +{ + "joomla": { + "api_key": "your-joomla-api-token", + "update_token": "your-automated-updates-token" + } +}