RCPCH API access management within Discourse
- Ensure Docker is installed and running
- Check out the main Discourse GitHub repo (https://github.com/discourse/discourse)
- Check out this repository
- Create a symlink between the main Discourse repo and this repo
- In the Discourse repo run
ln -s [location of this repo] plugins/discourse-apim
- In the Discourse repo run
- Follow the Discourse Docker development instructions
d/boot_dev --init- Run the Rails backend in one terminal:
d/rails s - Run the Ember frontend in another:
d/ember-cli
- Self service generate API credentials for individuals (ie our free tiers)
- Show monthly API usage for individuals
- Generate a monthly CSV of usage across all subscriptions
- Combine customers with old and new subscriptions into a single row in the CSV
- Show monhtly API usage for paying customers (ie members of the appropriate Discourse group)
- Show existing API credentials to paying customers
- Regenerate new API credentials (internally saving old API keys for reference where appropriate)
- Support APIs using OAuth credentials
Each row in the plugin UI is a combination of three Azure APIM concepts:
- User
- One to one mapping with a user in our Discourse forum
- For Discourse groups (ie paying customers) we create a single user representing the group
- Product
- One to one mapping with an API
- Free products do not require approval and must have quota or rate limiting
- Paid for products require approval and are only shown to users within a customer group in Discourse
- Subscription
- Essentially the API key, the mechanism for a user to consume a product
- Each user (including customer group ones) should have only one subscription per product
- They may however have older ones that are no longer active or come from an old APIM instance
From now on if we refer to "User" below it can be both users that represent individuals on the free tier and a user representing a group.
The discourse plugion talks to the API management API directly:
- https://learn.microsoft.com/en-us/rest/api/apimanagement/apimanagementrest/api-management-rest
- https://learn.microsoft.com/en-us/rest/api/apimanagement/apimanagementrest/azure-api-management-rest-api-authentication#ProgrammaticallyCreateToken
To generate the list of APIs we combine the following API calls:
- Product - List By Service.
- For individual users we filter by products that do not require approval so they can only sign up to our free products.
- For a paid customer group we show the products they have been signed up for
- For administrators viewing either we show all products regardless, allowing them to match as they see fit
- User Subscription - List
- Contains a
scopefield against each subscription which we match against the products to show which ones they already have credentials for
- Contains a
To display API keys we can use:
To request a new API key is two API calls:
- User - Create Or Update
- It's fine to call that on every request as if the user already exists it won't fail
- The resource name is very picky but I think we can replace any non
[A-Z,a-z]character from their email with-. That way we don't need to use the Discourse user ID in Azure APIM.
- Subscription - Create Or Update
We save the user IDs as a custom field on the appropriate Discourse user or group. This allows us to manually change them to accomodate those generated by hand in the Azure UI before this plugin was built.
We also need a list of additional subscription IDs so that we can calculate usage even if the subscription has been recreated or to accomodate subscriptions from a previous APIM instance in Azure.
To generate usage:
- Reports - List By Subscription
- Call this hourly with monthly time ranges back as far as we want to go
- Persist the results (currently Redis, should be a normal Rails model in the future)
- Calculate usage reports by pulling all the data out of the database
- Show usage for an individual user by filtering by a given set of subscription IDs stored as custom fields