The Kong Konnect team recently launched the Portal Management API, which allows users to manage their Developer Portals with one API. That means you can easily manage your portal settings, appearance, application registrations, and registration settings easier than before. 

In this blog, I’ll walk you through two scenarios that we expect the portal management API can help streamline: 

1. Automating developer management without needing manual developer approval
2. Understanding which developers are consuming (or not consuming) your APIs and taking steps to unblock developers where they may be blocked

Automating developer approvals

Manually approving developer applications is OK when there are one or two per week, but when you’re running at scale, this very quickly becomes painful. It’s more than just clicking the approve button. Managing developers means ensuring they’re onboarded, approved, and delegated proper permissions in a timely fashion.

The permissions aspect is key. Developers should only see the APIs that they’re contractually entitled to. However, applying permissions manually is time consuming and error prone. Let’s develop automation around the new portal management API so that we can approve trusted partners and assign them to teams at scale. 

To accomplish this we’ll take the following steps:

1. Fetch a list of recent developer registrations
2. Auto-approve any developers based on their email
3. Assign permissions based on the developer's email domain
4. Run this script automatically every hour

You can see the entire script we’re using here to process newly registered developers. 

The API provided by the Portal Management API returns data in the following format:

{
    "data": [
        {
            "created_at": "2023-08-03T23:45:50.042Z",
            "updated_at": "2023-08-03T23:45:50.042Z",
            "id": "b5f13fcb-190f-4418-a051-79c163770050",
            "email": "peter@arsenal.com",
            "full_name": "Arsenal",
            "status": "pending",
            "application_count": 0
        },
        {
            "created_at": "2023-08-22T22:22:12.708Z",
            "updated_at": "2023-08-22T22:22:12.708Z",
            "id": "6084e049-3a1d-4b62-89a0-970750082016",
            "email": "andrea@intermilan.com",
            "full_name": "Andrea",
            "status": "pending",
            "application_count": 1
        },
        {
            "created_at": "2023-10-25T00:04:11.286Z",
            "updated_at": "2023-10-25T00:05:15.291Z",
            "id": "15075e88-bb30-437a-9d0b-64f1aec8cd0e",
            "email": "mike@aol.com",
            "full_name": "Mike",
            "status": "pending",
            "application_count": 0
        }
	...
    ],
    "meta": {
        "page": {
            "total": 6,
            "size": 100,
            "number": 1
        }
    }
}

We call the GET /portals/{portalId}/developers endpoint in the get_newly_registered_developers() function, which returns a list of pending developers.

At this point, we want to auto-approve the developers. To do this, we call the process_pending_devs function:

def process_pending_devs(pending_developers):
    for developer_id in pending_developers:
        domain = pending_developers[developer_id]
        if domain in mapped_teams:
            # first approve their signup
            approve_developer(developer_id)
            # then assign them to the appropriate team (can also do this in a batch, per team)
            team_id = email_to_team_mapping[domain][1]
            assign_developer_to_team(developer_id, team_id) 

This function will check whether or not the developer (based on the domain of their email address) is in our trusted set of partner developers. If they are, it will approve their registration, and then assign them to the team corresponding to their email address.

The approve_developer function approves trusted developers with a call to PATCH /portals/{portalId}/developers/{developerId}:

def approve_developer(id):
    try:
        url = base_url + "/portals/" + portal_id + "/developers/" + id
        payload = {"status": "approved"}
        response = requests.request("PATCH", url, json=payload, headers=headers)
        print(response.text)
    except Exception as e:
        print("Error approving developer:", id, e)

Once the developer is approved, permissions need to be assigned so that they can consume the API. The assign_developer_to_team function updates the developer’s team mappings accordingly with a call to POST /portals/{portalId}/teams/{teamId}/developers:

def assign_developer_to_team(dev_id, team_id):
    try:
        url = base_url + "/portals/" + portal_id + "/teams/" + team_id + "/developers"
        payload = {"id": dev_id}
        response = requests.request("POST", url, json=payload, headers=headers)
        print(response.text)
    except Exception as e:
        print("Error assigning developer", dev_id, "to team", team_id, e)

In just 95 lines of code, we’ve taken a process that was time consuming and error prone and automated it with the Portal Management API.

Instead of needing to manually verify and approve new developer signups, we’re now approving any developer signups coming from trusted partner domains by running a cron job on our desired cadence.

Instead of needing to manually assign teams to said developers, we’re automatically assigning teams (and their associated product permissions) to these trusted partner developers.

Not bad for a morning’s work, right?

If you want to build on what you’ve learned today, why not try one of the following use cases?

• You could add additional verification before assigning developers to teams. For example, you could inspect each team and ensure there are available API Products that can be viewed/consumed. For Teams that don’t yet have any active developers, you may want to double check that a) Products were assigned to it and b) the roles for those Products were correctly assigned.
• If you have a “General” or “Public” team, instead of rejecting non-partner developers, you may want to assign them this non-privileged team role so they can view/consume non-privileged APIs.

Identifying blocked developers

After a week or two after having the above code in production, you realize that not all partners are using your APIs. This may be due to two factors:

• They don't have the right access permissions
• They’re blocked for other reasons

Kong Konnect provides the building blocks you need to create usage reports to help identify and unblock these stuck developers. Let's build these two reports:

1. Developers who need to be assigned permissions
2. Developers blocked for other reasons

Report 1: Developers who need to be assigned permissions

We want to make sure our team permissions were assigned appropriately so that our developers can create applications and register to consume our APIs. We’ll use portal management APIs to discover which developers haven’t consumed any APIs.

We’ll incorporate the following endpoints into our script:

• Get all developer applications with GET /portals/{portalId}/applications
• Get teams developer is assigned to with GET /portals/{portalId}/developers/{developerId}/teams
• Get roles for those teams using GET /portals/{portalId}/teams/{teamId}/assigned-roles

You can find the script we’re using here. We’ll step through the relevant functions below.

1. First we get all developer applications in our get_all_apps() function with a call to GET /portals/{portalId}/applications:

def get_all_apps():
    try:
        url = base_url + "/portals/" + portal_id + "/applications"
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()["data"]
        else:
            print("Error:", response.status_code)
            return []
    except Exception as e:
        print(f"Error in get_all_apps: {e}")
        return []

2. Next, in our get_apps_no_reg() function, we filter just on applications that have 0 successful registrations (meaning they aren’t consuming any of our APIs). We’ll focus only on developers who don’t have the relevant consumer permissions in Report 1.

We determine consumer permissions per developer with two calls. First, we retrieve all teams that our developer is assigned to with GET /portals/{portalId}/developers/{developerId}/teams. We get the following response:

{
	"meta": {
		"page": {
			"number": 1,
			"size": 10,
			"total": 1
		}
	},
	"data": [
		{
			"id": "d3874c1b-2fc7-4d0e-9d58-1ce5307ec1d2",
			"name": "Inter Milan",
			"description": "Inter Milan Team's API",
			"created_at": "2023-11-14T18:06:57Z",
			"updated_at": "2023-11-14T23:00:37Z"
		}
	]
}

Next, we check the roles for those teams using GET /portals/{portalId}/teams/{teamId}/assigned-roles. We get the following response:

{
	"meta": {
		"page": {
			"number": 1,
			"size": 10,
			"total": 1
		}
	},
	"data": [
		{
			"id": "30f1f1c6-f55f-48c3-90bc-0fb62b07356b",
			"role_name": "API Viewer",
			"entity_region": "us",
			"entity_type_name": "Services",
			"entity_id": "1f398e86-4d5d-490c-a447-70340b1481e3"
		}
	]
}

“API Viewer” permissions tell us that this developer can’t actually consume any of our APIs because they don’t have the “API Consumer” role. We add this developer to our “Developers needing Consume permissions” report. We loop through all of our developers to find any other developers in this situation. 

Note: If we wanted to get more info on this service id (1f398e86-4d5d-490c-a447-70340b1481e3) we could call GET /api-products/{id}. This would tell us more about how many versions of this API exist, when it was created and updated, which portals it’s published to, and the API name and description.

Report 2: Developers blocked for other reasons

Now we’ll create a report with developers who do have the right consumer permissions but who still haven’t registered for any API product versions in the last 48 hours since they’ve created their application. We go through the same two steps as we followed from Report 1, however this time, at the second step we’ll focus on developers who do have the right permissions.

The has_permissions check in our get_apps_no_reg() function checks for any applications that have the right permissions but haven't registered to consume any API Product versions 48 hours after being created. We add these developers to the Blocked Developers report and make a note to follow up with them. Perhaps these developers couldn’t understand our documentation. Perhaps they don’t understand our use cases for why they would want to use our APIs. Or perhaps they got a little carried away watching football and abandoned their app development. Whatever the reason is, we feel more confident knowing who they are.

Conclusion

There you have it! By incorporating these three endpoints into our script, we’re now able to automatically alert the relevant API Product owners to developers who may need following up with — either because they need more permissions or because they may need additional assistance. Actions like these help ensure our developers can more quickly get started and get building.

Note this was a very scoped-down example of how to manage developer permissions / notifications. If implementing in your own environment, you may want to take the following into consideration: 

• How frequently should you reach out to developers if they’re not progressing in consuming your APIs? 
• Are consumption patterns different between different developer teams? And should correspondence mirror that accordingly?

If you want to dive into the code, you can see the entire script we used here or read the docs.

Have any questions or additional use cases you’d like to see documented? Reach out to us on LinkedIn or X.