tnscorcoran / 3scale-discover-apis

3scale Service Discovery / API Catalog.

Introduction

API search and discovery can be a key requirement for organizations exposing APIs. This is a particularly strong requirement for larger organizations with disparate and dispersed development teams. A key driver behind this need is prevention of duplication of effort. We frequently run into situations where one team writes and exposes an API which has already written and exposed, either partially or completely elsewhere within the enterprise. By creating a central repository of APIs, where APIs can be searched for and discovered, this situation can be avoided.

In this article, we highlight and demonstrate a solution that can be deployed on the 3scale Developer Portal – to allow such search and discovery. The template are available at the 3scale Discover APIs Github repository. This community based solution was developed and is mainly contributed to by 3scale API evangelist, Nicolas Grenie.

We walk through creating a working example whose end result is a searchable catalog that resembles the following - though for simplicity we just add the member element:

Pre-requisites

There are 2 simple prerequisites to implement this solution.

• To implement the first part of this workshop, you’ll just need a free 3scale account - available at https://www.3scale.net/signup/. You will be given a 3scale administration URL, something like: https://-admin.3scale.net
• A Github account.

Implementation

We take the approach of building on the 3scale repository, walking through the end-to-end steps to add a Members API to a new Catalog which we’ll expose on the 3scale Developer Portal. Go ahead and execute the following steps:

• Upload your OAS (i.e. Swagger) JSON specification to your 3scale account. There are 3 ways to do this:

  • Copy the specification into the Active Docs section of the 3scale Administration Portal. It’s done by Creating a new spec here: https://-admin.3scale.net/admin/api_docs/services
  • This can also be done using the ActiveDocs Spec Create endpoint in your 3scale API: https://-admin.3scale.net/p/admin/api_docs#/account_management_api
  • This can also be doing using the Import Active Docs section of the 3scale CLI

  For convenience I have created a prepopulated one for our Members API here. This is useful for illustration but to actually use it for API calls, you’ll need to update the spec as described in API Documentation

• Download the preconfigured versions of the 4 files required to build the API catalog which I placed in my github repository:

  • apidetails (the Documentation added per API)
  • apilist (the Catalog page itself)
  • apis.json (a JSON spec containing various details on each API )
  • image for Members API (image that will appear on the catalog)

• Upload the 4 files to your 3scale CMS as described in more detail on the 3scale repository:

  • Member's image: Fill in as follows
  • apidetails. This contains the details of each API when you drill into it. Fill in as follows. Note to click Liquid Enabled: Fill in as follows
  • apilist. This is the catalog overview page - which draws its individual catalog entries from apis.json below. Fill in as follows:
  • apis.json. Fill in as follows (note empty Layout):
  • This contains the details inside apis.json for each catalog entry - normally an API. The highlighted area should be repeated per API: Make your substitutions into the red highlighted elements:
    • Service ID. Get this under your APIs menu:
    • Swagger System name. Same as you entered creating your OAS spec in the first Implementation step above, i.e. member Catalog image for this API you created previous - something like: https://.3scale.net/images/member (Note omission of -admin as it’s a Dev Portal asset)
    • Tags. These are strings that when entered in the Search box should return your API.
    • Swagger URL. Dev Portal host followed by /swagger/spec/.json, e.g. https://.3scale.net/swagger/spec/members.json

  Save then Publish.

• Test out the catalog

  • Go to your API List screen and select Preview at the bottom of the code text box (not shown in image). !(preview-apilist)[https://access.redhat.com/sites/default/files/images/10-apilist-view-1.png]

We only have 1 entry in our catalog, our Members API, so searching is superfluous. However if we had multiple APIs, as shown in the example catalog in the Introduction above, we could search on the keywords we entered in that section of apis.json.

Conclusion

Congratulations, you’ve created your first API Catalog and deployed it on the 3scale Developer Portal.