RFE: Working with system_name and not id

[nmasse-itix]

The 3scale toolbox is being improved to become the recommended way to configure and deploy services in 3scale. This fits in a broader approach of Continuous Delivery that has been started by several customers / communities (I personally maintain the threescale-cicd ansible role. Those approaches are using different means to drive the 3scale admin portal, some are using the 3scale-cli other (like the threescale-cicd role) are using the 3scale REST APIs.

If we want to make the 3scale_toolbox the de facto standard for interacting with 3scale, we need it to be usable in a CI/CD approach.

At a glance, here are the features I expect from the 3scale toolbox :

• RFE: Make the toolbox idempotent #81: Is idempotent
• RFE: Working with system_name and not id #82: Works with system_name and not service_id
• RFE: Provide a parseable output (JSON / YAML) #83: Can output human readable information as well as json or yaml (akin to oc cmd -o yaml)
• RFE: Have a standard way to report errors #80: Have a standard way to report errors

Working with system_name and not id

Currently, the 3scale_toolbox and the underlying 3scale APIs are using numerical IDs to reference the object to work on. At the same time, a system_name is present on each object with a human readable name and a unique constraint. As a user, I know that I want to update the service "my-service" but using the numerical ID is harder. 

In an infrastructure as code approach, the state of the system is determined by a formal description. The system can be completely determined by this description. When using numerical id, it is not anymore possible since the description would depends on the state of the system.

Last but not least, customers that have a separate installation of 3scale for their DRP site have different id's for the same service on both site. This means the CI/CD pipeline that deploys the service on the main site and on the DRP site needs to either do the discovery by itself or have a mapping table.

Proposition

The 3scale_toolbox uses the system_name instead of the numerical id to reference the object to work on. Then it can translate the system_name to the numerical id to finally call the underlying 3scale API.

Example

3scale copy service -t my-prod-api -s dev -d prod my-dev-api

This feature needs to be in the toolbox's core so that every plugin can leverage this feature.

[andrewdavidmackenzie]

If we use detection of (non-negative) integer values in the input, then we could have both options without adding options/commands or dropping the ability to refer to services by IDs.

That would restrict the use of service-names that are integers.

[mikz]

We don't offer finding by system name for most of the objects in our APIs, so this would require changes on the API side anyway.

And then we can basically just do find by id or system_name anyway on the GET endpoint.