Developer Portals, Catalogs, or Marketplaces?

Ikenna: Hello, welcome to the API governance for scale podcasts where we discuss scaling API platforms, API governance and API delivery in the enterprise. I'm your host, Ikenna Wewu ⁓ at Ikenna Consulting. And today we'll be talking about developer portals, API catalogs, API marketplaces. What are these? What are the differences between them? Which ones do you need? these different access model to APIs. To help us explore this area today, we have with us today Dr. Miriam Grice, ⁓ is the Principal Integration Architect at Adosys. Welcome Miriam ⁓ a in Human-Computer Interaction, ⁓ and over course of her career, she's worked deeply with APIs, and she's a regular speaker at API conferences all across Europe. Welcome Miriam, how are you? Miriam Greis: Hi, welcome. Thank you very much for the invitation to the podcast. So I'm really looking forward to our conversation. Ikenna: Good, good, good. It's my pleasure to have you here with us. yeah, Miriam, us a bit how you got started with APIs in the first place. Yeah, go on. Miriam Greis: Yeah. I mean, as you already said, I did a PhD in human computer interaction. So APIs is maybe not the nearest topic, but on the other hand, as my LinkedIn profile also says, APIs are user interfaces too, User interfaces for developers. So when I started getting into consulting actually around eight years ago, my first project was a project to build, guess what, an API developer portal. And that's why we're here today, right? Ikenna: Yes. Yeah. Wow. Cool. And that leads us to API developer portals, right? ⁓ you know, Miriam, before we talk about that, was ⁓ at Summit, right, last year, ⁓ and gave this great presentation. And so I said, you know, I have to get Miriam on this podcast to talk about this. ⁓ But first ⁓ started about the pain points that consumers face, you know, when trying to access APIs. Miriam Greis: Yes. Ikenna: things around discoverability, onboarding, integration, business alignment. Can you just into these things a little bit more for us and just tell us what they are, what they mean? Miriam Greis: Yes. I think if you're thinking about exposing APIs or introducing an access model for APIs, like how do people find an API? Then one of the biggest problems that I always, always saw there is that especially in large enterprises, people don't find the API they're looking for, right? They're struggling with discovery. Where is this API? Which team provides the data? I have no clue. I need to figure out. And especially if not all APIs are somewhere listed very easily, it gets very complicated to find out where. is actually the stuff that I need. What API can I use? Right. And that leads to also lots of people building, for example, duplicates, right. We're using something they shouldn't use because they can't find what they're looking for. then the second problem is the onboarding because very often it's not really clear. How do I start? If I never used an API before, which happens, right? There are lots of people who started using APIs. They don't really know how authentication works. They don't really know how to do a quick call to the API, which tool to use. Ikenna: learning. Miriam Greis: use for it. So onboarding can be very complicated, especially if you have lots of unexperienced developers working with APIs. And then of course, integration and usage is a big topic. Like, does this API fit my use case? Does it allow me, like, does it have a rate limit that's maybe against my use case? Can I use it in my environment? What's the, what's the... Data criticality, right? Is that even allowed to use it in my context? Stuff like this, which is usually very difficult to answer if you don't have a good like tooling where you can see all these things. And the last thing is of course the business focus, right? If enterprises want to get APIs to the public world, then there are a lot more questions regarding. Ikenna: Mm-hmm. Miriam Greis: How do we do the pricing? What should it cost that you need to make transparent to people, right? To the people who are looking for the APIs and who want to know, can I use this for my business or is this good for me to use for business? Yeah. Ikenna: Yeah. Yeah. And so we have this issues that consumers face that you've explained. so in the enterprise, we need to solve it. ⁓ ⁓ we come across all these different access models, developer portals, catalogs, and all of them. How we think about this in terms of how ⁓ they're Which should we use where? Because what you've seen, and I'm sure you've seen this Miriam, is across the industry, the terminology on these things is so kind of so different. know, people use the same word to mean different things. So, in fact, why have you actually found it important to talk about how these things are different? Yeah. ⁓ Miriam Greis: Yeah, I think you can add more names to this list. mean, call it integration hub or call it whatever, right? I just picked three, but there are lots more like names out there. Why I chose this is because the first project I talked, I worked on that I talked about before the one of building a developer portal that was actually not only meant for developers. So people, expected business people to look on the developer portal as well. But if you think about it, a developer portal already has developer in the title, right? Ikenna: You Miriam Greis: So who will visit the portal and think it's for them, right? Probably the developers. So with picking your name, you already pick a specific target group, or you already pick a specific feature set that people expect from your portal or platform or catalog, call it whatever you want it right now. Right. So it's important to think about what are the features that you really want to offer and what do people expect if you call it a developer portal? Ikenna: Exactly. ⁓ Miriam Greis: I would be disappointed if I go there and I cannot generate credentials or I don't have a sandbox. I cannot play around with the API. As a developer, I expect this, right? If I go to a catalog, I would be disappointed if there's only five APIs in there and if I cannot filter and search very well and drill down, right? So a different creates different expectations from people what to find there. ⁓ Ikenna: Hmm. Yeah, really good point that expectation. I think I guess that also depends like that that habos on the audience, right? It's like thinking about the audience and starting from the audience in terms of which access model you you use, you know, how important do you think it is about thinking about the audience you want to build this solutions for? Miriam Greis: Yeah, I think that should be actually the first thought about it. Like who do I want to reach with this access thing, whatever I call it, right? Do I want to reach the developers? Do I want to be highly technical or do I want to write something that's like a list, like a catalog that may, that maybe also includes some governance or do I really want to have a marketplace focus? I want to publish my APIs to a professional marketplace. Like this could be something like, I think some people will know. like plugin marketplaces or stuff like the Visual Studio Code plugins or the Amazon plugins or wherever you can find plugins for a specific tool, right? So do I want to participate in something like that? And then I have a very different audience. need lots of different information. I need to polish my APIs in another way. I need to offer different functionality, right? So the audience should be first. What do I want to achieve when doing these APIs? Who do I want to reach? ⁓ Ikenna: Yeah. Yeah. And so, so, know, give us your, your, your distinctions on, on, these tools, right? Cause the other one you mentioned in your talk is API registry, you know? So, so how, you know, how, do you differentiate between API catalog, API registry, ⁓ marketplace, you ⁓ all the, all of them. Yeah. Miriam Greis: I think that's important. Yes. Yes. So that was the missing piece that I mentioned in my, in my talk, right? I build it up with saying what's a catalog, what's a developer portal, what's a marketplace. And then the registry for me is a tool, which is the binding glue, right? I need a single source of truth for all my APIs, no matter where they are offered in a ⁓ marketplace or whether they are just internal, they're external, they have different audiences. Ikenna: Hmm. Miriam Greis: Nevertheless, I need a single source of truth, right? I want to know which APIs do I have in my organization and what are they doing? Because otherwise I lose track of the governance, right? So, I really want a governance and lifecycle management that's clear, like which APIs are there. And I think most companies misuse the catalog for it. So the catalog and the registry are the same tool, which means the catalog lists thousands of APIs. Like I saw... Ikenna: Yeah. Miriam Greis: I saw companies that have more than thousand APIs in their catalog without categorization even. So you're like, well, how should anybody find anything in this catalog? It's not at all sorted. It's not curated. So I think the usual thing is I put everything in my catalog, then I have the full view, but then nobody finds anything in the catalog anymore. Right. So the question is the registry should maybe be for everything, but the other tools should be restricted to the things that really like. Ikenna: Yeah. Miriam Greis: Like in a certain quality or for certain audience, not putting everything in one tool and then hoping that people will find what they're looking for. Right. So I think that the view to the audience, the catalog, the developer portal, the marketplace, they don't have to contain everything. They have to contain what's important for the audience. But then you need the tool that stores everything that makes it easy to publish to these consumer consumers or consumer channels. Right. Because otherwise as a provider. Ikenna: Yeah. Miriam Greis: You don't want to tell a provider well, you have to publish your API in the developer portal and in the catalog and in the marketplace and in the external tool, in the internal tool. I mean, there are many companies having internal and external developer portals or catalogs. So you need to publish twice and so on. So the question is, where's the single source of truth where it lives, right? And that should be, in my opinion, a kind of registry where you really know this is all I have. And from there I can decide what to put where, right? And what needs to go where for which audience. Yeah. So that's the idea behind it. Ikenna: Yeah, yeah, makes sense. Makes sense. When you look at, know, right now in the market, there's so many vendors, so many solutions out there for catalogs, know, for registries, for developer portals and all that. When you look at what's out there in the market, from your perspective, do you feel like most say, API catalog solutions have the features you would like, especially API catalogs, API registries, because you talked about that life ⁓ seeing the life cycle of the API and evolution of the API. Do you feel that most solutions have the features that would allow Miriam Greis: Yes. Ikenna: you know, product owners or whoever get the visibility, the lifecycle status and all the features they need or are there kind of features that I really, that you say, that you'd say, I really wish, you know, this catalog or this registry had ⁓ feature or Y feature. Miriam Greis: I think what I realized with many big companies, they actually tend to build it themselves. That's what I saw with many companies. They've built their developer portals or catalogs themselves because the tool that comes with the API management, usually if you're a big company, you have an API management system, whatever it is. Usually the catalogs or developer portals that come with them are not sufficient, right? So they have a certain set of features. But usually never the set of features that a client wants. I think that's very, that's very common, right? So I think the problem is that most of these tools try to do too much, right? They're trying to do everything, but not focusing on one audience group either. Like so, so I know that my first project where I built the developer portal, we actually built an external one and an internal one in the same project, right? Different portals with different target audience, differently styled like One in the internal style, one in the external style. And this was hand built because company said, well, the one that comes with the API management, that's not well enough for external because it looks ⁓ as nice as we want to present ourselves. And, for we also need something completely different. doesn't fit. Right. So I think ⁓ the point ⁓ usually people don't buy another. Marketplace catalog solution or developer portal solution. They either take the one that comes with the API management anyway, or they build their own one because they're saying, well, this doesn't fit and we don't get another tool, right? So it's very difficult. Ikenna: Yeah, yeah, yeah. am, there's just off your talk, there's this great, I love ⁓ diagram that you have up. I just want to share that for the viewers. ⁓ And this is just showing kind of what you described as ⁓ these access channels, right? Like your API registry ⁓ that source source ⁓ going to all this. Miriam Greis: Yes, let's do it. Ikenna: different ⁓ access channels. ⁓ I really like this because it captures it, doesn't it, ⁓ of the access model that you describe. Can you tell us a bit more here? Miriam Greis: Yes. Yes. So as you say, the idea is the API registry is the single source of truth. And from there you can sync to any access channel. And this can be anything else, right? Call it integration hub, call it whatever fits your audience group, whatever speaks to your audience group, right? This doesn't have to be one of those three that I picked for my talk, right? An access channel can be anything theoretically, right? That you consider is good for people to access your API. Ikenna: Yeah. Miriam Greis: Maybe it can also be ⁓ something AI related nowadays, right? You could have an access channel, especially for AI tooling or whatever, Whatever you pick as an access channel. And then below we have the different consumers. So that's what we talked about before. Think about what is the audience group of these specific ⁓ channels? What should be the audience and what do they expect to find? What are the key things that are different? Ikenna: Mm. Miriam Greis: from the other access channels, what are the key features that they need, right? So that's on the arrows, as you can see. So for the developer portal, the API docs onboarding and SDKs, all these things for the catalog, the discoverability and governance aspect, and for the marketplace, the monetization and partnership things. So think that things that make these access channels specific, right? And offer the target group what they need. And as I said, another consumer could be AI, could be right next to here. And you could think about what's the... access channel that I want to offer for them to discover my APIs, right? And where is it located? How does it feel from the registry and so on. Ikenna: Absolutely, that makes so much sense. I'll just kind of stop sharing here. When you've been in projects where you're building this, know, dev portals or API catalogs or all these different things, do you see as some of the... biggest challenges or common challenges that you find when you're trying to create that kind of solution. I'm sure you need to talk to different kinds of teams and different people involved. What are the things that are forefront in your mind whenever you come to a project where you need to create one of these things? Miriam Greis: I think the most important part is it has to be easy for providers to get this stuff in there and it has to be clear what they need to do. Because if you have a nice developer portal or catalog and there's nothing in there nobody knows how to get it there or the process is very complicated. That's a real problem. Right. And the other side as well, if you don't have a good governance and everything lands in there, you will, you would like. Ikenna: Hmm. Miriam Greis: right go right away into an API sprawl and nobody finds anything anymore. So you need to make it easy for providers to publish and you need to give them good guidance on the governance to make sure you have high quality things in your access channel. Whatever it is right in a registry you can have crappy APIs no problem but then please don't expose them to any consumers if not necessary right they don't need to see the crappy stuff that might be needed for some projects or might be Ikenna: Yeah. Hmm. Hmm. Miriam Greis: Like legacy APIs or whatever, but then don't show them in your access channels. Right. So I think that's what most people overlook. Even if you built the tools itself for the consumers, you have a lot of work on the provider side as well. I think that's an important aspect that I learned because you need to enable the providers to actually bring their stuff to the tools. Ikenna: Yeah, So enable the providers to publish the API contracts, API descriptions into these ⁓ access channels. ⁓ Miriam Greis: Yes. And not only the contracts. mean, if you, if you go for a marketplace, also need business information, pricing information, marketing information. So you need a lot more than just the contract, right? For an internal developer portal or catalog, that's maybe, that's usually the only thing that's there, right? You get the open API file, like as API contract, and you hope it has enough information. and not just a one sentence description, right? you hope for a bit more. But yeah, so, so the question is how much documentation do you need and where do you put this documentation? Where can people put it in to get it into the process as well? Additional stuff that they need for the APIs. Because very often I saw that especially the internal tooling, the internal catalogs, they only offer to show the open API file and that's it. Right. And people say, well, I have more documentation. I would like to provide something more. it's like, you can. Ikenna: Hmm. Miriam Greis: put a link somewhere in your open API with external docs and that's it. And then you have to find another way to publish it somewhere. And then someone puts it in Confluence. Someone puts it in a word, someone puts it wherever, you know, and then this starts again that you get very incoherent set of documentation, right? yeah. ⁓ Ikenna: Yeah. Exactly. Talking about catalogs and things, like you've mentioned, in ⁓ they this build versus buy decision. You've given an example already. ⁓ Imagine organization that they have API sprawl or whatever, they now want to consolidate all their API somewhere or their API description somewhere. Miriam Greis: Yes. Ikenna: And they face this decision, do I buy an API catalog? Do I use the one that comes with my API management solution if it has one? Do I build one myself? do you think organizations should approach that? Yeah. Miriam Greis: I think the first question again is who should be the audience? That should be the first thing you tie down. And then really talk to some people in your audience and check what do they need? Like really do a requirement analysis, not just take a tool or buy a tool. And then if you have the clear criteria, you can go to the tools or solutions and check. Do they really fulfill my criteria that I want to do, want to have? think most, most companies, when they look for a tool, they don't have this clear, they say, well, we need something to show our APIs, but they don't really know who it should be for or what the feature should be. And I think if you know that it gets a lot easier to evaluate tooling against it. Besides, if you just say, well, we need something because we have a sprawl, right? And then I think, I think the next thing. Ikenna: Yeah. No, go on, go on, Miriam, yeah. Miriam Greis: The next thing is really getting the governance right, right? ⁓ Or checking how these tools make the governance. I think that's a very important aspect, especially if you already have a sprawl. I about it in my talk, the story, like one the catalogs that I saw, that was actually, it had no good categorization and filtering and it had ⁓ also thousands APIs. So teams wouldn't find the APIs anymore. And the APIs were all ordered alphabetically. So teams started to prefix the APIs with an underscore just to have it at the top of the list. And at some point you had APIs with five underscores. Right. And I also saw this as a recent customer. also teams started to add post fixes in their API names or stuff like that, because they just cannot find their APIs anymore themselves in the catalog. Right. So if you. If you have science like that, you clearly have a problem, right? And you need to think more about governance and how to really sort those things and make them findable and searchable that people don't have to do tricks like that to find it. Ikenna: Yeah, I mean, really, really great points. know, talking about starting from requirements, understanding what people actually need, what the teams actually need and using that to drive. I think that's a really great way to actually find the simplest thing that works, you know, find the simplest thing that meets the requirements rather because the opposite thing is to, is to buy the API catalog or developer portal that has the most features, right? Miriam Greis: Yes. Yes. Ikenna: I can be have the most features be the most expensive, but people would probably not use, you know, 80 % of the features or whatever, you know, so yeah, really great point about really being requirements driven and approaching it from that perspective. And also, yeah, the governance thing as well, you know, making sure it fits in that governance life cycle, that governance process. Yeah. Yeah. Miriam Greis: That's funny because we just talked about it today with one of my colleagues about a similar topic. It was not exactly about catalogs, but we came to the same solution that most tools the API space offer lots of features that nobody needs, right? Actually, you just need a bit of features. So it's really important to start with them. Sometimes the minimal solution can be enough, right? And then to enhance from there. Ikenna: Yeah. Miriam Greis: You probably don't need to full blown, I can do everything because as I said in my talk as well, you either do one thing, right? Or everything a bit, right? It's difficult to get something that does everything to do everything very greatly. So, so the question is really, where do you want to focus? I mean, easy from tools to tell you we can do everything, but usually. Yeah. Then it's maybe not. Ikenna: Mmm. Yeah. Miriam Greis: the greatest thing you can do for one consumer group, right? So it's just an average for everyone, let's say. Ikenna: Yeah. Yeah. Yeah. ⁓ like to, ⁓ one of the things I like to ⁓ as we, ⁓ know, as I end every episode is to ask, you know, if I'm, if I'm an API product owner or API product manager or API platform team, I'm trying to start out in this space, right? I'm trying to, I'm trying to ⁓ about who my Users are externally and internally and create an access model for them to access my API information. ⁓ I begin? Where will I begin? What are the areas you ⁓ have me begin? I know you've talked about them already, a few of them, but yeah, what are tips you can give me on where to start? Miriam Greis: Yes. I think the first question I would ask is, are you an API provider or are you really someone in a central position? Because I often have the feeling that single teams in a company want to change something, but they can't really, right? Because if you, a consumer access channel will be something central. So even if you as a team provide a really good channel, that doesn't help if no one else jumps on, right? So that's very important. Don't waste your effort if this cannot work as a global solution. because there's always, I think in API or in the API space in general, it's very hard to do local optimization in general because in the end, the... The great thing happens when all APIs are the same way intuitively in the same tool with the same things, right? That's what makes it awesome and what makes it easy. Even if one team locally optimizes, other team will optimize differently and then the APIs will still not be the same or match or be displayed in the same way, right? Even if they try their best because just... domains are very different work very differently. You have different types of developers, different types of systems, right? So you need a kind of central point to start this. So best, best point to start at this, in my opinion, an API management or API platform, API developer experience team, something like that, a more central team that can really handle this task and also feels responsible for it, right? For all, all the people, right? And then I think what I would do first is, Ikenna: Yeah. Miriam Greis: Talk to a few API product managers or API providers in your company. Try to figure out what needs do they have from a provider side? What, who do they want to expose their APIs to? That's also interesting because if you, if you're saying we're doing a marketplace and nobody wants to expose APIs externally, then you have a marketplace that nobody uses. So figure out who do they want to reach? Why? What do they want to even publish or what do they already have? Because most of them will already have something and then as I said check your target audience if they tell you who's going to use the API's and if you have a good picture of where these talk to the target audience figure out what requirements they have to actually select what's starting with first. Ikenna: Yeah, Really fantastic tips there to get started in this space. Thank you. Thank you so much, Miriam. If we, know, ⁓ people want to find out more about this or out more about you and the work you do, how can ⁓ reach out? Miriam Greis: Yeah, so there's a blog post on actually exactly this topic on the code centric blog from my former employee. So we can of course share links. So if you want to read more about this specific topic, find the graphics that Ikena showed and all the other things, you can read it up there. And you can always find me on LinkedIn, of course. So if you want to, if you have any questions or want any other API related content, feel free to follow me. Ikenna: Absolutely, absolutely. Yeah, and so great, great blog posts here with lots of, you know, really great information on this topic. So what having a look at this. Miriam Greis: Also a nice comparison on the consumer needs and so on the table in there exactly. Ikenna: Yeah. Yeah, I'll put a link to this in the show notes for the podcast, both on the audio and the YouTube version. Thank you so much, Miriam. It's been fantastic having you on the show and really look forward to seeing you again and listening to more of your talks at future conferences ⁓ this year. Yeah. Miriam Greis: Perfect. Yes, thank you very much, looking forward to it too! Ikenna: Thank you. See you later.