The 3scale CMS tools project provides the ability to interact with 3scale’s Content Management System programmatically. The project also demonstrates API-first code generation.
The included Command Line Interface (CLI) tool is a rewritten and enhanced version of the same tool written in Ruby, available at hguerrero/3scale-cms. The CLI tool has been re-implemented using Java and Quarkus.
|
Warning
|
The 3scale CMS tools, as well as the 3scale Content Management API that they rely upon, are not supported by Red Hat. These tools and the undocumented 3scale Content Management API may change at any moment without any guarantee of backward compatibility. Therefore, these tools are not recommended for production use. |
This repository contains the following artifacts:
The 3scale CMS tools project provides documentation for the 3scale Content Management API, which can be found in the repository at: rest-client/src/main/resources/api-spec/3scale-cms.yaml.
The documentation uses the OpenAPI Specification v3.0 format. It describes the available endpoints for managing CMS objects, along with the endpoint of the Account Management API, which is used for lookup of the Developer Portal base URL and the Developer Portal access code.
The 3scale CMS tools project provides a standalone REST client JAR. The JAR is available in the GitHub Packages maven repository.
To use the JAR in a Maven project, first include the following repository definition:
<repositories>
<repository>
<id>threescale-cms-rest-client</id>
<name>Unofficial 3scale CMS REST Client</name>
<url>https://maven.pkg.github.com/fwmotion/3scale-cms</url>
<layout>default</layout>
<releases>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>To include the client JAR as a dependency, use the following dependency definition:
<dependency>
<groupId>com.fwmotion</groupId>
<artifactId>3scale-cms-rest-client</artifactId>
<version>1.0.0</version>
</dependency>The 3scale CMS tools project provides a CLI tool that provides a convenient mechanism for interacting with the 3scale Content Management API. It is implemented using Quarkus and picocli, with a compiled and assembled container image provided in GitHub Packages.
Run the CLI tool using Podman:
podman run -it --rm -v .:/cms:Z ghcr.io/fwmotion/3scale-cms:latest --helpRun the CLI tool using Docker:
docker run -it --rm -v .:/cms ghcr.io/fwmotion/3scale-cms:latest --helpSample Tasks and Pipelines for Tekton are available under the samples directory of this repository:
The 3scale Developer Portal consists of 3 primary types of objects:
You must have an account in 3scale. The CMS contents can be viewed in the Developer Portal section of the admin portal for that account.
To use the 3scale-cms command you need to provide a few parameters:
-
An ACCESS_TOKEN, which can be used instead of a PROVIDER_KEY. The access token must be granted permissions to both the Account Management API and the hidden Content Management API.
-
The PROVIDER_KEY, which can be found in the Account tab of your admin portal (only visible to the users with "admin" role). The PROVIDER_KEY will be ignored if an ACCESS_TOKEN is specified.
-
The PROVIDER_DOMAIN of your admin portal. e.g.
https://mycompany-admin.3scale.net -
The DIRECTORY, which specifies a local directory path for determining files to upload, download, or compare between the local filesystem and the 3scale CMS content. This is an optional parameter. If omitted, the
3scale-cmscommand will choose a working directory following the rules described in this note.
Create a directory where you will work on your CMS locally:
cd ~ mkdir my_cms cd my_cms
The 3scale-cms command has five actions:
-
info - show information about contents of the CMS and the local files. It accepts the optional parameter: 'details'
-
diff - show the difference in contents between the CMS and the local files. It accepts the optional parameter: 'details'
-
download - download all the contents of the CMS (no parameter). Or specify a file or section (with its contents) to download
-
upload - upload all the local files (no parameter). Or specify a file or section (with its contents) to upload
-
delete - delete all (that can be deleted) or a specific entry in the remote CMS
|
Note
|
The
|
This command displays information about contents of the CMS and the local files. It accepts the optional parameter: 'details'
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN infoOutput should resemble:
Contacting CMS at PROVIDER_DOMAIN/admin/api/cms to get content list
The layout 'main_layout' in file '/l_main_layout.html.liquid' was selected as the default layout for uploading new pages
118 items found in CMS
7 ignored local files (matching patterns in '.cmsignore')
152 (non-ignored) local files
8 implicit folders due to file/template system_names containing '/'Use
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN info detailsto get the list of specific files in each of those four categories:
-
CMS contents elements
-
Locally ignored files
-
Local files that are not being ignored
-
List of folders created due to CMS elements with '/' in the name
This command displays the differences in contents (taking into account ignored files and implicit folders) between the CMS and the local files.
Use
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN diffOutput should resemble:
Contacting CMS at PROVIDER_DOMAIN/admin/api/cms to get content list
The layout 'main_layout' was selected as the default layout for uploading new pages
Summary:
0 files to be created locally
0 files to be updated locally
17 files to be created on CMS
1 files to be updated on CMSto get the list of specific files to be applied on 'download' and 'upload' use:
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN diff detailsIf used without an additional file/directory name parameter, this command downloads the entire contents of the CMS that either doesn’t exist locally, or is out of date locally (based on timestamps of files/folders).
If a filename is specified, then only that file is downloaded (if it exists in the CMS and is out of date locally).
If a directory name is specified, then it and all its contents (recursively down) are checked and any content that is found to exist in the CMS and is out of date is downloaded.
|
Note
|
Existing files are overwritten on download, and missing files are ignored unless the Files matching patterns in |
If used without an additional file/directory name parameter, this command uploads all local files found under the current working directory that are either out of date in the CMS (based on timestamps) or do not exist in the CMS.
If a filename is specified, then only that file is uploaded (if it exists in the CMS and is out of date, or does not exist in the CMS).
If a directory name is specified, then it and all its contents (recursively down) are checked and any content that is found to not exist in the CMS or is out of date in the CMS is uploaded.
Files matching patterns in .cmsignore are skipped.
If used without an additional parameter this command will attempt to delete all content under the root section on the remote CMS (indicated via domain parameter).
If used with a specific filename it will attempt to delete that entry in the remote CMS.
If used with a folder name, it will attempt to delete that section and all sections and content under it in the CMS.
|
Warning
|
This action cannot be undone, and should be used with caution. Double-check the domain parameter you intend to use. |
The 3scale-cms command enables you to do offline editing, changes or
version control of the contents of a CMS in your admin portal in 3scale.
In the CMS it is possible to create a file, a template or a section. Examples of files are an image, a JS script, or a CSS stylesheet. A template is generally
content in an .html.liquid file. A section is a hierarchical folder in the CMS
for storing other elements.
The mirror used locally is a hierarchy of folders that mirrors the content organization in the CMS. Thus sections in the CMS are mirrored as directories on your local file system, and the elements below that section in the CMS are placed inside that directory.
|
Note
|
It is possible to create a file/template in the CMS that is served from a path other than its location in the CMS. e.g. a file called |
It is often desirable to have some files in the local directory that you do not want to upload to the CMS. Examples could be files used in the version control of your CMS contents (e.g. a .git folder), or files used in the testing or Continuous Integration of your contents (e.g. travis.yml file).
To have the 3scale-cms command ignore these files, they can be added to the .cmsignore file in any directory of the CMS mirror. These files use the 'glob' format to allow specifying patterns of files and directories, not just specific files.
When a local file of type .html or .html.liquid is created that does not have the _ (underscore) prefix to indicate it is a partial or the l_ (l-underscore) prefix to indicate it is a layout, then the tool assumes that the new file is a page and uploads it as such.
|
Note
|
By convention, partial filenames are expected to have the prefix |
When a page is created in the CMS, the layout to apply to it must be specified. To allow for automatic use of the tool without user intervention the tool chooses a default layout from the layouts in the CMS to use for new files it creates.
Upon start-up the tool examines the list of layouts in the CMS and chooses one as the default layout for new pages that will be created.
If no layouts are available in the CMS, the tool will not run.
If you wish to use a different layout for a newly created page, you currently have to go to the CMS in the admin portal and change it manually.