Hi! I was wondering if someone here built an IDP relying on API as the way for their users to consume services and capabilities provided by the platform. I’ve heard about the API first approach a lot but, at least in my scenario, it’s hard to think it could be the way to go. A developer that want a service I would say is more keen to come to a self service portal and interact with it to have the resources provisioned rather than code the interaction with the platform: I don’t see a use case where coding that approach could make sense and to be honest, I would say if we have a scenario worth to code, it would be for the platform to code it and make it available as an E2E use case. I see the API approach some useful for AWS, Azure or a cloud provider in general, but not sure for an Internal Developer Platform. Happy to year your feedback and also your scenario if you built an API based platform.

What do you think developers would do with the provisioned resources? Apis are the foundation of a useful development platform. It's how the developers interact with the functionality exposed by the platform. Note that the api need not necessarily interact with a remote resource, in case that's an area of confusion

I mean.. just as an example: let me say one of the provisioned resource is Jenkins project with standard pipeline.. where the API interaction would be useful here?

With that example the definition is a bit of a stretch, but the Jenkins project is going to have some requirements on the Repository- scripts it expects to exist or tools that it will invoke. These are the "apis" that the developers write against to make the Jenkins project useful

Thanks Jordan. All of this make sense to have tools / capabilities interacting one with the other but still I don’t see where such APIs are useful to be exposed to platform’s customers directly

Simple concepts make developers stick to APIs. Repeatability. Single source of truth. Fit with their current toolchain and style of work. Suppose you establish the platform interaction on an API or “as code” level. In that case, a developer ever only needs to look into the VCS and read the configuration stored directly with the code he is working on to understand what is happening. If you think about large setups, the scale factors of standardization, better assignability of developers to changing projects and the like will catch up pretty soon as well. From the top of my mind - not a complete list of concerns obviously…

I think I'm misunderstanding you, because I am unaware of any other (reasonable) ways to expose anything to the platform's customers

Usually configuration code falls into that category. So I have to invoke “it depends” on you - because it actually depends on what the functionality is that you want to drive. To stay in your Jenkins example - you would drop the configuration code for that “pipeline as code” into the source code repo and let the developer work on that.

Thanks, for something like Jenkins I think that makes sense (though I'd argue something like that runs the risk of restraining users too much - but sometimes that can be a good thing). But what about the other bulk of what you'd expect from an IDP? If no code can reach it at all (which no apis implies) I can't imagine it being a platform I'd want to be writing against.

Please provide a concrete example and I will try to wrap my head around it. Currently nothing jumps my mind that would be “no code can reach it at all”.

If code can reach it, you're calling an api

Heh… it’s late (or early? 😄 here already). I totally miss-read your last sentence

If no code can reach it at all (which no apis implies) I can't imagine it being a platform I'd want to be writing against.

and I can heartily agree with it. If it has no API, it is most probably something that neither developers nor I would like to be part of a platform that they use for their day-to-day work.

Ha, I was wondering if I was missing something obvious!

Well… I think I can understand your point of view but possibly I am a bit biased from the current scenario I am in. Let me say.. developers need to start a new project: they need a repo, they need a jenkins project, they need a Grafana tenant… well, as per the scenario I am in today I hardly see the team asking for this through API / code, instead they would like to rely on a visual approach (self-service catalog?) also because some of those requests will require a validation on the back of the process before to ignite the provisioning part. Is that just a matter of cultural change / mindset or am I missing something?

I think the difference is that you seem to be focused on the first 5% (made up number) of what I would think of an IDP as providing. All of the hard/interesting aspects of the platform happen after the initial setup. I'm not convinced an API to create a repo is useful, but I wasn't really thinking of that as part of the platform with my original statements. I do think that it is now that you say it like that, but if that's all that's being provided, I don't necessarily think I would call that a development platform. I'd call it a scaffold or something

@Leonardo Romanato, you’re focusing on the creation flow of a new project. This usually doesn’t happen too often and the lifetime of a project is where the bacon is. A self-service portal is in essence for this just a nice JS-driven button to execute the setup script. After that, the developers need to actively engage with the content of the repo that was created on a daily basis. To stay on the Jenkins example -you create that instance using an automated setup script. After that the platform team can totally care for all of the maintenance and operations of that Jenkins instance (and all of them) because developers don’t really care as long as Jenkins is executing their pipelines. To facilitate this separation of concerns, you put the pipeline as code in the repo. If the UI of Jenkins is the only way for the developer to interact with Jenkins and the storage of the relevant data is in that Jenkins, things start to get complicated. Maintenance windows become stop-the-world events. Backups become life savers because it is not about “Jenkins as a service” anymore but about “this specific Jenkins instance that has my pipeline data”. #insert a myriad of other concerns here# You could state that any system that is not API driven and can externalize its configuration is adding to the dependencies of the roles “developer” and “platform engineer” and, by that nature, making the collaboration more complex.

Ok, now it make sense! Thanks for thee useful suggestions. As you said, I think I was too focused on a specific part of the process

Great question! I helped to build an internal developer platform at a large insurance company several years ago, and we did indeed take the API-first approach. I believe our reasoning went something like, "We know we need to provide some core capabilities and iterate on them, and it's going to be easier to do that by starting simply with an API and early adopters." We eventually developed a really nice web portal, but not before one of our platform-consuming lines of business wrote their own portal, encompassing many of their LOB-specific developer workflow concerns

Big agrees that an API is not about how users will consume things, it is about how to build a versioned, evolveable, set of features. An API can (and likely will) end up with a number of UIs in front. I am seeing a lot of Backstage (or maybe Atlassian Compass) for the GUI you seem to be interested in, I am also seeing a lot of in house CLI tools and chat bots. Depends on the users!