3scale - automate creation of management artifacts for external APIs

[gbengataylor]

The external APIs for the microservices will be managed via 3scale. It would be helpful to automate the creation of the 3scale management artifacts for the external APIs. 3scale includes a toolbox, https://github.com/3scale/3scale_toolbox, to manage services via the command line.

1. Manage via OpenAPI spec
   Using Apicurio, the external APIs can be created and pushed to the git repo.

2. Manage via a csv

The toolbox can generate the artifacts from the input source. Need to investigate which of these is more manageable and also generates more of the artifacts

Another alternative would be to write a script/playbook that uses the 3scale Management REST API to create all the management artifacts.

[gbengataylor]

install 3scale toolbox https://github.com/3scale/3scale_toolbox#installation. Requires Ruby 2.3 and above

gem install 3scale_toolbox

**If having issues installing 3scale toolbox, run
docker run --rm -it quay.io/gbengataylor/3scale-toolbox:latest
This will start a container where you can run the 3scale commands

CSV Test

echo "service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
Movies ,Movies (Biography),GET,/movies/biography/,api_key,movies_biography,metric
Movies ,Movies (Drama),GET,/movies/drama/,api_key,movies_drama,method" >> svc.csv

set access token and 3scale admin URL
ACCESS_TOKEN=
THREESCALE_ADMIN_URL=
For e.g.
ACCESS_TOKEN=d5af6b19da8381014f59e79245ae242dd5ea8dfe1a8a6c0e2bc481366fxxxxx
THREESCALE_ADMIN_URL=3scale-demo-admin.3scale.net
Run the 3scale import
3scale import csv --destination=https://${ACCESS_TOKEN}@${THREESCALE_ADMIN_URL} --file=svc.csv

What gets installed

1. Service
2. Metrics (as defined in csv, in this case two including the default hit metric)
3. methods (as defined in csv - in this case one method)
4. mapping rules (in this example, 3 for the two GET REST paths plus the root / path)
5. API security/auth method specified
6. By default uses the API gateway included with the 3scale install (on-prem or SaaS)

OpenAPI Spec Test

Create your OpenAPI v 2.0 spec. We like Apicurio (https://www.apicur.io/). This can be run locally in a container or OpenShift. There is also a live SaaS version. Note that the toolbox only supports OpenAPI v2
An example can be found here - https://raw.githubusercontent.com/gbengataylor/3scale-toolbox-image/master/svc.yaml

Documentation for this mode can be found here - https://github.com/3scale/3scale_toolbox/blob/master/docs/openapi.md

To import, set access token and 3scale URL
ACCESS_TOKEN=
THREESCALE_ADMIN_URL=
For e.g.
ACCESS_TOKEN=d5af6b19da8381014f59e79245ae242dd5ea8dfe1a8a6c0e2bc481366fxxxxx
THREESCALE_ADMIN_URL=3scale-demo-admin.3scale.net
Run 3scale import
3scale import openapi -d https://${ACCESS_TOKEN}@${THREESCALE_ADMIN_URL} https://raw.githubusercontent.com/gbengataylor/3scale-toolbox-image/master/svc.yaml

What gets installed

1. Service
2. 3scale ActiveDoc Documentation associated with the Service (not published)
3. API security/auth method. In this case it is the default - API KEY. The method can be changed via command line
4. 2 methods, one for each URL endpoint
5. the default hit metric
6. mapping rules. In this case, 2 were created for the 2 REST paths. The root / path not created
7. By default uses the API gateway included with the 3scale install (on-prem or SaaS)

Comparison

Both imports are similar, however, the OpenAPI spec also includes the ActiveDoc documentation, while the csv is more flexible in defining metrics and methods. For the purposes of this demo, the OpenAPI spec probably serves us better as a the single source of truth

We will still need to

• Update the private URL of the microservice on the 3scale service (ie. service integration)
• Possibly add the CORS policy chain
• In the case for the self-managed gateway, add an openshift route for that service
• Create application plans. Ideally we would be able to create plans with different access permissions
• Publish the ActiveDocs

TODO

add OpenAPI specfor this demo spec this repo
create scripts to generate 3scale artifacts using the OpenAPI spec
Figure out how to update service integration, publish ActiveDocs, and create Applications Plans via the 3scale toolbox or the 3scale Management REST API or using the 3scale API as code operator that was in Dev last fall

[dudash]

Can this automate or have hooks for SSO integration too? Do you think it's more or less complex for newbs to understand than using the non-toolbox way?

I actually build the API for the boards service using Apicurito. And then automate the endpoint creation using swagger-tools and tagging the YAML with x-swagger-router-controller.

That's for the service API on the inside of the gateway.