Kong-plement Your ServiceHub With a Dev Portal
Two of the best (in my opinion) features in Konnect are the ServiceHub and Dev Portal. However, they're also two of the most misunderstood. Aren't they the same thing? Why would you need a ServiceHub vs. Dev Portal?
Well, I'm glad you asked! The really quick version is that ServiceHub is like your warehouse, where all your products are stored. It's a comprehensive collection of everything that you have. Your Dev Portal is more like your storefront. It contains only the things you want to promote, and you present them in a more user-friendly way.
That's the 20-second explanation. Continue reading, and we'll explore the differences between the two and dive deeper into the functionality of each.
ServiceHub
Let's start with the ServiceHub, as it's the first thing you'll see when you register for Konnect. This is where you'll see all of your running services and have the ability to configure your service versions, routes and plugins.
My sample project for Konnect is Gorilla Bank, a fake banking institute. This means I have services related to account management, money collection and foreign exchange rates.
ServiceHub is the system of record for all available services at Gorilla Bank. It allows developers to discover and consume existing services, speed up development and reduce duplication.
What's great about ServiceHub is that although you can use it to manage your Kong Gateway runtime, you don't have to.
At Gorilla Bank, we have some legacy systems that don't use Kong, but I still want them to be discoverable for developers. By creating a ServiceHub entry and an associated version, we can provide metadata and documentation for the service without linking it to a Kong Gateway implementation.
If you use Kong Gateway for any of your services, usage within that service will show up in the Runtime Manager, which lives within ServiceHub. That way, you can keep track of usage at a glance, including any errors.
Having a single source of truth that shows any available APIs across a business is key to building alignment across your API strategy. A team rarely builds their own service because they want to—more often than not, they do so because they don't know that a service already exists. ServiceHub helps your teams understand what's available, how to use it and how each service is performing.
Dev Portal
Let's move on to the Dev Portal. Whilst the ServiceHub is for your internal development teams, the Dev Portal targets both internal and external consumers. You can control which APIs people can see and provide an easy-to-use console that allows consumers to try out the API directly in the docs.
By default, Kong secures your Dev Portal behind a login. This is useful if your APIs aren't ready for the general public to use. Once consumers register, their requests will show up in Konnect for approval.
Once you approve the registration request, the consumers will be able to log in to the developer portal and see any published services. At Gorilla Bank, we've published the Account Inquiry, Collect Money and FX Rates APIs for use by the public. The other APIs, such as Account Creation, are still private.
If your APIs are usable by the general public, you may want to explore the portal settings section of Konnect. You can make the portal entirely public or enable automatic approval of any registrations if you need to capture email addresses but want the content to be available to anyone without the added approval process.
No matter how well you design an API, some context is usually required when working with it. To help with this, Konnect allows you to upload a Service Document within ServiceHub, which Kong will show within the Dev Portal.
The Service Document is a markdown file containing any information you need to share with consumers. It can also contain anything that is valid markdown, including images.
In addition to the service document, the Dev Portal also allows you to upload an OpenAPI specification. The spec shows the available endpoints for the API, plus any available parameters and an example response.
You may have noticed the Try it Out section on the right. That section allows your customers to try out your API directly in the documentation. It provides the executed request in various languages (powered by our open-source httpsnippet project).
If you have different versions of an API available, switching between them is as easy as using the version dropdown at the top of the page. Likewise, suppose you've got many environments — in that case, you can specify multiple entries in the servers block in your OpenAPI specification. The developer portal will let your customers choose which environment to test against.
Finally, the View Raw button enables your consumers to download your specification and use it for anything they need. The Dev Portal uses it for documentation, but your customers could use it for mocking, code generation or a whole lot more.
Ready to Try Out Kong Konnect?
Thanks for sticking with me this far! We've taken a tour of Konnect's ServiceHub and Dev Portal. Hopefully, you're clearer on how they're different from each other and how each of them can enhance your API experience.
We're just getting started with Konnect, and I can't wait to share some advanced workflows using the Developer Center API with you, but that will have to wait for a future post.
Start a free trial, or contact us if you have any questions as you're getting set up.
Now that you have a better understanding of Kong Konnect's ServiceHub and Dev Portal, you may find these other tutorials helpful: